REST APIs

Overview Laravel recently introduced the `JsonApiResource` class in version 12.45, a significant update that aligns the framework with the official JSON:API specification. Historically, Laravel utilized an opinionated, flat structure for its Eloquent resources. This new feature allows developers to serve data in a standardized format that includes specific keys like `type`, `id`, and `attributes`, making it easier for standardized frontend clients to consume backend data without custom mapping. Prerequisites To follow this guide, you should have a baseline understanding of PHP and the Laravel framework. Familiarity with REST APIs and Postman for testing endpoints is recommended. You must be running Laravel 12.45 or higher to access the new resource class. Key Libraries & Tools * **Laravel Framework**: The core PHP framework providing the new API features. * **JSON:API Specification**: The industry-standard protocol for building APIs in JSON. * **Postman**: A tool used to visualize and test the differences between standard and JSON:API responses. Code Walkthrough Instead of extending the usual `JsonResource`, you now extend `JsonApiResource`. This small change fundamentally reshapes the output. ```php use Illuminate\Http\Resources\Json\JsonApiResource; class PostResource extends JsonApiResource { public function toArray($request) { return [ 'id' => $this->id, 'title' => $this->title, 'slug' => $this->slug, 'category' => new CategoryResource($this->whenLoaded('category')), ]; } } ``` In the standard `JsonResource`, the fields like `title` and `slug` appear at the top level of the `data` object. However, when using `JsonApiResource`, Laravel automatically nests these fields under an `attributes` key and extracts the `id` and `type` to the top level. This satisfies the strict requirements of the JSON:API spec without requiring you to manually rebuild the array structure. Global Configuration You can configure global metadata for your JSON:API implementation within the `AppServiceProvider` or a dedicated provider. This allows you to set versioning or extensions that apply to all resources. ```php use Illuminate\Http\Resources\Json\JsonApiResource; public function boot() { JsonApiResource::configure( version: '1.1', meta: ['api_status' => 'stable'] ); } ``` Syntax Notes The `JsonApiResource` class uses internal logic to wrap your `toArray` return values. While your resource file looks familiar, the framework post-processes the array to move everything into the `attributes` block unless it matches the reserved keys for `id`, `type`, or `relationships`. Tips & Gotchas One common point of confusion is the versioning string in the configuration. While the JSON:API website currently highlights versions 1.1 and 1.2, Laravel allows you to pass custom strings. Always verify your frontend client's expectations before hardcoding a version like `2.0` in your service provider.