{"id":295,"date":"2025-08-27T19:23:10","date_gmt":"2025-08-27T19:23:10","guid":{"rendered":"https:\/\/1v0.net\/blog\/?p=295"},"modified":"2025-08-27T19:23:12","modified_gmt":"2025-08-27T19:23:12","slug":"how-to-use-eloquent-api-resources-for-clean-apis","status":"publish","type":"post","link":"https:\/\/1v0.net\/blog\/how-to-use-eloquent-api-resources-for-clean-apis\/","title":{"rendered":"How to Use Eloquent API Resources for Clean APIs"},"content":{"rendered":"\n

How to Use Eloquent API Resources for Clean APIs<\/strong><\/h2>\n\n\n\n

Eloquent API Resources give you a clean, explicit layer to shape JSON responses. Instead of returning raw models (which may leak internal fields), resources let you control fields, nest relations, add meta and links, and keep your API consistent. In this guide, you\u2019ll build resources for posts and users, paginate collections, conditionally include attributes and relations, and add meta information\u2014then consume the API from a simple UI.<\/p>\n\n\n\n

<\/div>\n\n\n\n\n

1 – Create Models (Sample Domain)<\/strong><\/h2>\n\n\n\n

We\u2019ll use a simple domain: Post<\/code> belongs to User<\/code>. If you already have these, skip ahead.<\/p>\n\n\n

php artisan make:model Post -mf<\/code><\/span>Code language:<\/span> Bash<\/span> (<\/span>bash<\/span>)<\/span><\/small><\/pre>\n\n\n
This creates the model, a migration, and a factory. You\u2019ll use them to scaffold data for testing the API responses.<\/p>\n\n\n
\/\/ database\/migrations\/xxxx_xx_xx_create_posts_table.php<\/span>\nuse<\/span> Illuminate<\/span>\\Database<\/span>\\Migrations<\/span>\\Migration<\/span>;\nuse<\/span> Illuminate<\/span>\\Database<\/span>\\Schema<\/span>\\Blueprint<\/span>;\nuse<\/span> Illuminate<\/span>\\Support<\/span>\\Facades<\/span>\\Schema<\/span>;\n\nreturn<\/span> new<\/span> class<\/span> extends<\/span> Migration<\/span> <\/span>{\n    public<\/span> function<\/span> up<\/span>()<\/span>: void<\/span> <\/span>{\n        Schema::create('posts'<\/span>, function<\/span> (Blueprint $table)<\/span> <\/span>{\n            $table->id();\n            $table->foreignId('user_id'<\/span>)->constrained()->cascadeOnDelete();\n            $table->string('title'<\/span>);\n            $table->text('body'<\/span>);\n            $table->json('meta'<\/span>)->nullable(); \/\/ tags, reading_time, etc.<\/span>\n            $table->timestamps();\n        });\n    }\n    public<\/span> function<\/span> down<\/span>()<\/span>: void<\/span> <\/span>{\n        Schema::dropIfExists('posts'<\/span>);\n    }\n};<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
The migration includes a nullable JSON meta<\/code> field to demonstrate how resources can shape nested JSON cleanly.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
2 – Generate API Resources<\/strong><\/h2>\n\n\n\n
Create resources for Post<\/code> and User<\/code>. These classes transform models to JSON.<\/p>\n\n\n
php artisan make:resource PostResource\nphp artisan make:resource UserResource<\/code><\/span>Code language:<\/span> Bash<\/span> (<\/span>bash<\/span>)<\/span><\/small><\/pre>\n\n\n
Resources live in app\/Http\/Resources<\/code>. Each implements a toArray($request)<\/code> method that returns the exact JSON structure you want to expose.<\/p>\n\n\n
\/\/ app\/Http\/Resources\/UserResource.php<\/span>\nnamespace<\/span> App<\/span>\\Http<\/span>\\Resources<\/span>;\n\nuse<\/span> Illuminate<\/span>\\Http<\/span>\\Resources<\/span>\\Json<\/span>\\JsonResource<\/span>;\n\nclass<\/span> UserResource<\/span> extends<\/span> JsonResource<\/span>\n<\/span>{\n    public<\/span> function<\/span> toArray<\/span>($request)<\/span>: array<\/span>\n    <\/span>{\n        return<\/span> [\n            'id'<\/span>    => $this<\/span>->id,\n            'name'<\/span>  => $this<\/span>->name,\n            'email'<\/span> => $this<\/span>->email,\n        ];\n    }\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
This keeps the user payload minimal and explicit. If you don\u2019t want to expose emails publicly, omit or conditionally include it later.<\/p>\n\n\n
\/\/ app\/Http\/Resources\/PostResource.php<\/span>\nnamespace<\/span> App<\/span>\\Http<\/span>\\Resources<\/span>;\n\nuse<\/span> Illuminate<\/span>\\Http<\/span>\\Resources<\/span>\\Json<\/span>\\JsonResource<\/span>;\n\nclass<\/span> PostResource<\/span> extends<\/span> JsonResource<\/span>\n<\/span>{\n    public<\/span> function<\/span> toArray<\/span>($request)<\/span>: array<\/span>\n    <\/span>{\n        return<\/span> [\n            'id'<\/span>      => $this<\/span>->id,\n            'title'<\/span>   => $this<\/span>->title,\n            'excerpt'<\/span> => str($this<\/span>->body)->limit(140<\/span>),\n            'body'<\/span>    => $this<\/span>->when($request->routeIs('posts.show'<\/span>), $this<\/span>->body),\n            'meta'<\/span>    => [\n                'tags'<\/span>         => data_get($this<\/span>->meta, 'tags'<\/span>, []),\n                'reading_time'<\/span> => data_get($this<\/span>->meta, 'reading_time'<\/span>),\n            ],\n            'author'<\/span>  => new<\/span> UserResource($this<\/span>->whenLoaded('user'<\/span>)),\n            'created_at'<\/span> => $this<\/span>->created_at?->toIso8601String(),\n            'updated_at'<\/span> => $this<\/span>->updated_at?->toIso8601String(),\n            \/\/ Example link<\/span>\n            'links'<\/span> => [\n                'self'<\/span> => route('posts.show'<\/span>, $this<\/span>->id),\n            ],\n        ];\n    }\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
This resource exposes a short excerpt<\/code> for lists and includes the full body<\/code> only on the show route using when()<\/code>. The author<\/code> is wrapped in UserResource<\/code> and included only if the relation is eager-loaded (whenLoaded('user')<\/code>).<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
3 – Controller: Return Resources and Collections<\/strong><\/h2>\n\n\n\n
Use resources in controller methods. For collections, either use PostResource::collection($posts)<\/code> or make a separate PostCollection<\/code>. Here we\u2019ll keep it simple.<\/p>\n\n\n
\/\/ app\/Http\/Controllers\/PostController.php<\/span>\nnamespace<\/span> App<\/span>\\Http<\/span>\\Controllers<\/span>;\n\nuse<\/span> App<\/span>\\Http<\/span>\\Resources<\/span>\\PostResource<\/span>;\nuse<\/span> App<\/span>\\Models<\/span>\\Post<\/span>;\nuse<\/span> Illuminate<\/span>\\Http<\/span>\\Request<\/span>;\n\nclass<\/span> PostController<\/span> extends<\/span> Controller<\/span>\n<\/span>{\n    public<\/span> function<\/span> index<\/span>(Request $request)<\/span>\n    <\/span>{\n        $posts = Post::with('user'<\/span>)\n            ->latest()\n            ->paginate(10<\/span>);\n\n        return<\/span> PostResource::collection($posts)\n            ->additional([\n                'meta'<\/span> => [\n                    'copyright'<\/span> => '\u00a9 Your Company'<\/span>,\n                ],\n            ]);\n    }\n\n    public<\/span> function<\/span> show<\/span>(Post $post)<\/span>\n    <\/span>{\n        $post->load('user'<\/span>);\n\n        return<\/span> new<\/span> PostResource($post);\n    }\n\n    public<\/span> function<\/span> store<\/span>(Request $request)<\/span>\n    <\/span>{\n        $data = $request->validate([\n            'title'<\/span> => ['required'<\/span>,'string'<\/span>,'max:150'<\/span>],\n            'body'<\/span>  => ['required'<\/span>,'string'<\/span>],\n            'meta'<\/span>  => ['nullable'<\/span>,'array'<\/span>],\n        ]);\n\n        $post = Post::create($data + ['user_id'<\/span> => $request->user()->id]);\n\n        return<\/span> (new<\/span> PostResource($post->load('user'<\/span>)))\n            ->response()\n            ->setStatusCode(201<\/span>);\n    }\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
index()<\/code> returns a paginated collection wrapped by PostResource<\/code>, and additional()<\/code> appends custom top-level meta<\/code>. show()<\/code> returns a single resource. store()<\/code> validates input, creates the post, and returns the serialized resource with status 201.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
4 – API Routes and Pagination Shape<\/strong><\/h2>\n\n\n\n
Define API routes and see how pagination metadata\/links are included automatically when you pass a LengthAwarePaginator into ::collection()<\/code>.<\/p>\n\n\n
\/\/ routes\/api.php<\/span>\nuse<\/span> App<\/span>\\Http<\/span>\\Controllers<\/span>\\PostController<\/span>;\n\nRoute::get('\/posts'<\/span>, [PostController::class, 'index'<\/span>])->name('posts.index'<\/span>);\nRoute::get('\/posts\/{post}'<\/span>, [PostController::class, 'show'<\/span>])->name('posts.show'<\/span>);\nRoute::middleware('auth:sanctum'<\/span>)->post('\/posts'<\/span>, [PostController::class, 'store'<\/span>])->name('posts.store'<\/span>);<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Unprotected GET<\/code> routes serve public data. The POST<\/code> route requires authentication (e.g., Sanctum), keeping write operations secured.<\/p>\n\n\n\n
If you don\u2019t want the default wrapping key (data<\/code>) around your resource payloads, you can disable it globally:<\/p>\n\n\n
\/\/ app\/Providers\/AppServiceProvider.php (boot)<\/span>\nuse<\/span> Illuminate<\/span>\\Http<\/span>\\Resources<\/span>\\Json<\/span>\\JsonResource<\/span>;\n\npublic<\/span> function<\/span> boot<\/span>()<\/span>: void<\/span>\n<\/span>{\n    JsonResource::withoutWrapping();\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
With wrapping disabled, the collection returns an array at the top level alongside links<\/code> and meta<\/code> for pagination. Choose the style your clients expect.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
5 – Conditional Attributes and Merged Blocks<\/strong><\/h2>\n\n\n\n
Use helpers like when()<\/code>, mergeWhen()<\/code>, and whenLoaded()<\/code> to keep responses compact and context-aware.<\/p>\n\n\n
\/\/ app\/Http\/Resources\/PostResource.php (snippets)<\/span>\nreturn<\/span> [\n    \/\/ ...<\/span>\n    'is_owner'<\/span> => $this<\/span>->when(\n        optional($request->user())?->id === $this<\/span>->user_id,\n        true<\/span>\n    ),\n\n    $this<\/span>->mergeWhen($request->routeIs('posts.show'<\/span>), [\n        'full_body'<\/span> => $this<\/span>->body,\n        'meta'<\/span>      => $this<\/span>->meta,\n    ]),\n\n    'author'<\/span> => new<\/span> UserResource($this<\/span>->whenLoaded('user'<\/span>)),\n];<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
when()<\/code> includes fields only under certain conditions (e.g., current user is the owner). mergeWhen()<\/code> adds a block of fields for detail views without bloating list responses. whenLoaded()<\/code> safely includes relations if they were eager-loaded.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
6 – Eager Loading and N+1 Safety<\/strong><\/h2>\n\n\n\n
Resources don\u2019t fetch relations; they only serialize what you loaded. Always eager-load relations in controllers to avoid N+1 queries.<\/p>\n\n\n
\/\/ In PostController@index<\/span>\n$posts = Post::with('user'<\/span>)->latest()->paginate(10<\/span>);\nreturn<\/span> PostResource::collection($posts);<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Because user<\/code> is loaded on the query, UserResource<\/code> in PostResource<\/code> can serialize the author<\/code> efficiently.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
7 – Adding Top-Level Meta and Custom Status Codes<\/strong><\/h2>\n\n\n\n
Return HTTP status codes using the response()<\/code> helper, and add top-level meta<\/code> or links<\/code> when needed.<\/p>\n\n\n
\/\/ Example in store()<\/span>\nreturn<\/span> (new<\/span> PostResource($post->load('user'<\/span>)))\n    ->additional(['meta'<\/span> => ['created'<\/span> => true<\/span>]])\n    ->response()\n    ->setStatusCode(201<\/span>);<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
This returns the serialized post with a 201 Created<\/code> status and a meta.created<\/code> flag, which is handy for clients.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
8 – UI: Consuming the API from a Blade Page<\/strong><\/h2>\n\n\n\n
Here\u2019s a minimal UI that fetches \/api\/posts<\/code> and renders a list. You can adapt this to your marketing site or dashboard.<\/p>\n\n\n
<!-- resources\/views\/posts\/index.blade.php -->\n@extends('layouts.app'<\/span>)\n\n@section('content'<\/span>)\n<div class<\/span>=\"container<\/span>\">\n  <h1<\/span> class<\/span>=\"mb<\/span>-4\">Latest<\/span> Posts<\/span><\/h1<\/span>>\n  <div<\/span> id<\/span>=\"post<\/span>-list<\/span>\">Loading<\/span>...<\/div<\/span>>\n<\/div<\/span>>\n\n@push<\/span>('scripts<\/span>')\n<script<\/span>>\n  fetch<\/span>('\/api<\/span>\/posts<\/span>')\n    .then<\/span>(r<\/span> => r<\/span>.json<\/span>())\n    .then<\/span>(json<\/span> => <\/span>{\n      const<\/span> data = json.data ?? json; \/\/ supports wrapped or unwrapped<\/span>\n      const<\/span> list<\/span> = document.getElementById('post-list'<\/span>);\n      list<\/span>.innerHTML = ''<\/span>;\n      data.forEach<\/span>(p => {\n        const<\/span> card = document.createElement('div'<\/span>);\n        card.className = 'card mb-3'<\/span>;\n        card.innerHTML = `\n          <div class<\/span>=\"card<\/span>-body<\/span>\">\n            <h5<\/span> class<\/span>=\"card<\/span>-title<\/span>\">$<\/span>{p.title}<\/h5>\n            <p class<\/span>=\"card<\/span>-text<\/span>\">$<\/span>{p.excerpt}<\/p>\n            <a href=\"\/posts\/${p.id}\"<\/span> class<\/span>=\"btn<\/span> btn<\/span>-theme<\/span> r<\/span>-04\">Read<\/span><\/a<\/span>>\n          <\/div<\/span>>`;\n        list<\/span>.appendChild<\/span>(card<\/span>);\n      });\n    });\n<\/script<\/span>>\n@endpush<\/span>\n@endsection<\/span><\/span><\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
The UI calls your API, supports either wrapped ({ data: [...] }<\/code>) or unwrapped collection payloads, and renders cards with title and excerpt from the resource.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
Wrapping Up<\/h2>\n\n\n\n
Eloquent API Resources give you a declarative way to shape JSON: pick fields, conditionally include details, nest relations, add meta, and keep pagination consistent. Keep controllers focused on queries and authorization, and let resources handle presentation of data for clients. This makes for predictable, maintainable APIs that evolve gracefully.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
What\u2019s Next<\/h2>\n\n\n\n