{"id":21571055,"url":"https://github.com/treblle/api-responses","last_synced_at":"2025-07-22T20:33:42.653Z","repository":{"id":190365212,"uuid":"682479881","full_name":"Treblle/api-responses","owner":"Treblle","description":"Elevate your API response consistency with this specialized package. Designed for intuitive integration within your controllers, it guarantees straightforward and standardized API responses, simplifying the process for you.","archived":false,"fork":false,"pushed_at":"2024-11-27T03:19:11.000Z","size":107,"stargazers_count":21,"open_issues_count":2,"forks_count":0,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-07-17T11:51:51.383Z","etag":null,"topics":["api","api-monitoring","api-observability","api-response","backend","laravel","php","response","rest-api","restful-api","standardization","treblle"],"latest_commit_sha":null,"homepage":"https://www.treblle.com/","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Treblle.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-08-24T09:03:27.000Z","updated_at":"2025-02-11T22:04:22.000Z","dependencies_parsed_at":"2025-04-10T14:22:51.476Z","dependency_job_id":"84e17d63-08af-4c3d-aedd-945cfa13a31e","html_url":"https://github.com/Treblle/api-responses","commit_stats":null,"previous_names":["treblle/api-responses"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/Treblle/api-responses","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Treblle%2Fapi-responses","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Treblle%2Fapi-responses/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Treblle%2Fapi-responses/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Treblle%2Fapi-responses/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Treblle","download_url":"https://codeload.github.com/Treblle/api-responses/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Treblle%2Fapi-responses/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266567638,"owners_count":23949391,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-22T02:00:09.085Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-monitoring","api-observability","api-response","backend","laravel","php","response","rest-api","restful-api","standardization","treblle"],"created_at":"2024-11-24T11:14:46.052Z","updated_at":"2025-07-22T20:33:42.629Z","avatar_url":"https://github.com/Treblle.png","language":"PHP","readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://treblle-github.s3.us-east-1.amazonaws.com/github-header.jpg\"/\u003e\n\u003c/div\u003e\n\u003cdiv align=\"center\"\u003e\n\n# API Responses\n\n\u003c!-- BADGES_START --\u003e\n[![Latest Version][badge-release]][packagist]\n[![PHP Version][badge-php]][php]\n![tests](https://github.com/treblle/api-responses/workflows/tests/badge.svg)\n[![Total Downloads][badge-downloads]][downloads]\n\n[badge-release]: https://img.shields.io/packagist/v/treblle/api-responses.svg?style=flat-square\u0026label=release\n[badge-php]: https://img.shields.io/packagist/php-v/treblle/api-responses.svg?style=flat-square\n[badge-downloads]: https://img.shields.io/packagist/dt/treblle/api-responses.svg?style=flat-square\u0026colorB=mediumvioletred\n\n[packagist]: https://packagist.org/packages/treblle/api-responses\n[php]: https://php.net\n[downloads]: https://packagist.org/packages/treblle/api-responses\n\u003c!-- BADGES_END --\u003e\n\n\u003ca href=\"https://docs.treblle.com/en/integrations\" target=\"_blank\"\u003eIntegrations\u003c/a\u003e\n\u003cspan\u003e\u0026nbsp;\u0026nbsp;•\u0026nbsp;\u0026nbsp;\u003c/span\u003e\n\u003ca href=\"http://treblle.com/\" target=\"_blank\"\u003eWebsite\u003c/a\u003e\n\u003cspan\u003e\u0026nbsp;\u0026nbsp;•\u0026nbsp;\u0026nbsp;\u003c/span\u003e\n\u003ca href=\"https://docs.treblle.com\" target=\"_blank\"\u003eDocs\u003c/a\u003e\n\u003cspan\u003e\u0026nbsp;\u0026nbsp;•\u0026nbsp;\u0026nbsp;\u003c/span\u003e\n\u003ca href=\"https://blog.treblle.com\" target=\"_blank\"\u003eBlog\u003c/a\u003e\n\u003cspan\u003e\u0026nbsp;\u0026nbsp;•\u0026nbsp;\u0026nbsp;\u003c/span\u003e\n\u003ca href=\"https://twitter.com/treblleapi\" target=\"_blank\"\u003eTwitter\u003c/a\u003e\n\u003cspan\u003e\u0026nbsp;\u0026nbsp;•\u0026nbsp;\u0026nbsp;\u003c/span\u003e\n\u003ca href=\"https://treblle.com/chat\" target=\"_blank\"\u003eDiscord\u003c/a\u003e\n\u003cbr /\u003e\n\n  \u003chr /\u003e\n\u003c/div\u003e\n\nA package to help you keep your API Responses standardized.\n\n## Installation\n\n```bash\ncomposer require treblle/api-responses\n```\n\n## Usage\n\nThis package is easy to use, it is designed to be used within your controllers to return API responses that are simple and standardized.\n\n## Using the configuration\n\nYou can publish the configuration for this package using the following artisan command:\n\n```bash\nphp artisan vendor:publish --tag=api-config\n```\n\nThis will return the configuration file for this package. Currently, the configuration only covers headers used in responses.\n\n```php\nreturn [\n    'headers' =\u003e [\n        'default' =\u003e [\n            'Content-Type' =\u003e 'application/vnd.api+json',\n        ],\n        'error' =\u003e [\n            'Content-Type' =\u003e 'application/problem+json',\n        ],\n    ],\n];\n```\n\nThe `HeaderFactory` that is used in the response classes will pull with `HeaderFactory::default()` or `HeaderFactory::error()` depending if you are returning an error or a response.\n\nYou can override the available headers using the configuration file. This is executed outside of any middleware you may be using - which will merge in relevant Headers as required, such as Rate Limiting and Cache headers you may have set.\n\n## Returning a single model\n\nSome API endpoints just need to return a single model, in this situation you should use the `ModelResponse` which accepts a `JsonResource` representation of your model.\n\n```php\nfinal class ShowController\n{\n    public function __invoke(Request $request, User $user): Responsable\n    {\n        return new ModelResponse(\n            data: new UserResource(\n                resource: $user,\n            ),\n        );\n    }\n}\n```\n\n## Returning a collection of models\n\nOther API endpoints want to return a collection of models, in these situations you should use the `CollectionResponse` which accepts an `AnonymousResourceCollection` which is a collection of Models transformed through API Resources.\n\n```php\nfinal class IndexController\n{\n    public function __invoke(Request $request): Responsable\n    {\n        return new CollectionResponse(\n            data: UserResource::collection(\n                resource: User::query()-\u003eget(),\n            ),\n        );\n    }\n}\n```\n\n## When something goes wrong\n\nThe best approach when something goes wrong in your API, the best approach is to allow this to bubble up the your Exception Handler and manage how you respond in one central place.\n\n```php\nfinal class Handler extends ExceptionHandler\n{\n    public function register(): void\n    {\n        $this-\u003erenderable(fn (ModelNotFoundException $exception, Request $request) =\u003e new ErrorResponse(\n            data: new ApiError(\n                title: 'Not Found',\n                detail: $exception-\u003egetMessage(),\n                instance: $request-\u003epath(),\n                code: ErrorCode::NOT_FOUND-\u003evalue,\n                link: 'https://docs.domain.com/errors/not-found',\n            ),\n            status: Status::NOT_FOUND,\n        ));\n    }\n}\n```\n\n## Sending a simple message response\n\nSometimes all you need to do is send a simple message back through your API. Perhaps you are pushing the logic to a background job.\n\n```php\nfinal class StoreController\n{\n    public function __invoke(StoreRequest $request): Responsable\n    {\n        dispatch(new RegisterProvider($request-\u003epayload()));\n        \n        return new MessageResponse(\n            data: 'We have accepted your request, and are processing this action.',\n            status: Status::ACCEPTED,\n        )\n    }\n}\n```\n\n## Sending back a more complex message response\n\nAt times you want to pass back a message as well as some data, perhaps to signify actions that need to be taken.\n\n```php\nfinal class LoginController\n{\n    public function __invoke(Request $request): Responsable\n    {\n        return new \\Treblle\\ApiResponses\\Responses\\ExpandedResponse(\n            message: __('auth.login'),\n            data: [\n                'type' =\u003e 'login',\n                'attributes' =\u003e [\n                    'mfa' =\u003e __('auth.mfa_required'),\n                ]\n            ],\n        )\n    }\n}\n```\n\n## General Usage\n\nThis package currently contains the following responses:\n\n- `ModelResponse`: For responding a single model resource.\n- `CollectionResponse`: For responding a collection of models for a resource.\n- `ErrorResponse`: For responding when you have encountered an Error.\n- `MessageResponse`: For when you are returning a simple message.\n- `ExpandedResponse`: For when you want to send a message and some data in the response.\n\nPlease note, the `ErrorResponse` is not idea for any `400` responses as these are user errors such as wrong resource or Validation problems.\n\n\n## Community 💙\n\nFirst and foremost: **Star and watch this repository** to stay up-to-date.\n\nAlso, follow our [Blog](https://blog.treblle.com), and on [Twitter](https://twitter.com/treblleapi).\n\nYou can chat with the team and other members on [Discord](https://treblle.com/chat) and follow our tutorials and other video material at [YouTube](https://youtube.com/@treblle).\n\n[![Treblle Discord](https://img.shields.io/badge/Treblle%20Discord-Join%20our%20Discord-F3F5FC?labelColor=7289DA\u0026style=for-the-badge\u0026logo=discord\u0026logoColor=F3F5FC\u0026link=https://treblle.com/chat)](https://treblle.com/chat)\n\n[![Treblle YouTube](https://img.shields.io/badge/Treblle%20YouTube-Subscribe%20on%20YouTube-F3F5FC?labelColor=c4302b\u0026style=for-the-badge\u0026logo=YouTube\u0026logoColor=F3F5FC\u0026link=https://youtube.com/@treblle)](https://youtube.com/@treblle)\n\n[![Treblle on Twitter](https://img.shields.io/badge/Treblle%20on%20Twitter-Follow%20Us-F3F5FC?labelColor=1DA1F2\u0026style=for-the-badge\u0026logo=Twitter\u0026logoColor=F3F5FC\u0026link=https://twitter.com/treblleapi)](https://twitter.com/treblleapi)\n\n### How to contribute\n\nHere are some ways of contributing to making Treblle better:\n\n- **[Try out Treblle](https://docs.treblle.com/en/introduction#getting-started)**, and let us know ways to make Treblle better for you. Let us know here on [Discord](https://treblle.com/chat).\n- Join our [Discord](https://treblle.com/chat) and connect with other members to share and learn from.\n- Send a pull request to any of our [open source repositories](https://github.com/Treblle) on Github. Check the contribution guide on the repo you want to contribute to for more details about how to contribute. We're looking forward to your contribution!\n- \n## Testing\n\nTo run the test suite:\n\n```bash\ncomposer run test\n```\n\n## Credits\n\n\u003ca href=\"https://github.com/Treblle/api-responses/graphs/contributors\"\u003e\n  \u003cp align=\"center\"\u003e\n    \u003cimg  src=\"https://contrib.rocks/image?repo=Treblle/api-responses\" alt=\"A table of avatars from the project's contributors\" /\u003e\n  \u003c/p\u003e\n\u003c/a\u003e\n\n## LICENSE\n\nThe MIT LIcense (MIT). Please see [License File](./LICENSE) for more information.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftreblle%2Fapi-responses","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftreblle%2Fapi-responses","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftreblle%2Fapi-responses/lists"}