A Laravel API Resource is used to transform Eloquent models into JSON responses in a clean, consistent, and secure way.

Why Use API Resources?

  • Control which fields are returned
  • Format data consistently
  • Hide sensitive fields
  • Customize API responses easily
  • Ideal for React, Vue, Mobile Apps

1.When Should You Use API Resources?

Use API Resources when:

  • You are building REST APIs
  • You don’t want to return raw models
  • You need different response formats
  • You want clean, maintainable code

2.Creating an API Resource

Command:

php artisan make:resource UserResource

This creates:

app/Http/Resources/UserResource.php

3.Basic Resource Structure

namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

class UserResource extends JsonResource
{
public function toArray(Request $request): array
{
return [
'id' => $this->id,
'name' => $this->name,
'email' => $this->email,
];
}
}

Explanation:

  • JsonResource → Base class for API resources
  • toArray() → Controls JSON output
  • $this → Refers to the model instance

Returning a Single Resource

Controller Example:

use App\Http\Resources\UserResource;
use App\Models\User;public function show($id) { $user = User::findOrFail($id); return new UserResource($user); }

JSON Output:

{
"id": 1,
"name": "John Doe",
"email": "john@example.com"
}

5.Returning a Resource Collection

Controller:

public function index()
{
return UserResource::collection(User::all());
}

JSON Output:

{
"data": [
{
"id": 1,
"name": "John Doe",
"email": "john@example.com"
},
{
"id": 2,
"name": "Jane Doe",
"email": "jane@example.com"
}
]
}

6.Using Resource with Pagination

public function index()
{
return UserResource::collection(User::paginate(10));
}

Output includes pagination meta:

{
"data": [...],
"links": {...},
"meta": {...}
}

7.Conditional Attributes

Return fields only when needed.

return [
'id' => $this->id,
'email' => $this->when($request->user()->isAdmin(), $this->email),
];

8.Conditional Relationships

return [
'id' => $this->id,
'posts' => PostResource::collection(
$this->whenLoaded('posts')
),
];

Controller:

$user = User::with('posts')->find(1);
return new UserResource($user);

9.Creating a Resource for Relationships

php artisan make:resource PostResource

class PostResource extends JsonResource
{
public function toArray(Request $request): array
{
return [
'id'    => $this->id,
'title' => $this->title,
'body'  => $this->body,
];
}
}

10.Adding Custom Meta Data

return UserResource::collection(User::all())
->additional([
'status' => true,
'message' => 'Users fetched successfully'
]);

11.Wrapping / Unwrapping Data

Default wrapper:

{
"data": {...}
}

Disable wrapper:

use Illuminate\Http\Resources\Json\JsonResource;

JsonResource::withoutWrapping();

12.Formatting Dates in Resource

'created_at' => $this->created_at->format('Y-m-d'),

13.Hiding Sensitive Fields

Instead of returning full model:

return $this->resource->only(['id', 'name']);

14.Full Example (User + Posts)

return new UserResource(
User::with('posts')->find(1)
);

Output:

{
"id": 1,
"name": "John Doe",
"posts": [
{
"id": 10,
"title": "Laravel API Resources"
}
]
}

Categorized in:

Laravel,