When building a REST API with Laravel, returning database models directly as JSON may seem convenient. However, as an application grows, you often need more control over the data returned to clients.
This is where Laravel API Resources become useful.
Laravel API Resources provide a clean way to transform Eloquent models into JSON responses. They allow you to control which fields are exposed, rename attributes, format relationships, add calculated fields, and create consistent API responses.
In this guide, you’ll learn how to create API Resources in Laravel from scratch using practical examples.
We’ll cover:
- What Laravel API Resources are
- Why API Resources are useful
- How to create an API Resource
- Transforming Eloquent models
- Returning resources from controllers
- Resource collections
- Conditional fields
- Relationships
- Nested resources
- Pagination
- Custom API responses
- Common mistakes
- Best practices
- Frequently asked questions
What Are Laravel API Resources?
Laravel API Resources provide a transformation layer between your Eloquent models and the JSON responses returned by your API.
Instead of returning an Eloquent model directly:
return response()->json($user);
you can create a Resource that defines exactly how the user should appear in the API response.
For example:
return new UserResource($user);
The Resource controls the final JSON structure.
Basic Flow
Database
↓
Eloquent Model
↓
API Resource
↓
JSON Response
↓
Frontend / Mobile App / Client
This separation gives your API a cleaner architecture and prevents database models from becoming tightly coupled to API responses.
Why Use Laravel API Resources?
Returning models directly is possible, but it can become problematic in larger applications.
Consider a User model containing:
id
name
email
password
phone
address
created_at
updated_at
internal_notes
You probably don’t want every field returned to the frontend.
With an API Resource, you can explicitly define the fields that should be exposed.
return [
'id' => $this->id,
'name' => $this->name,
'email' => $this->email,
];
This provides several advantages.
| Benefit | Description |
|---|---|
| Data control | Decide exactly what the API returns |
| Security | Avoid accidentally exposing sensitive fields |
| Consistency | Maintain a predictable response structure |
| Formatting | Transform dates and other values |
| Relationships | Control nested model responses |
| Maintainability | Keep transformation logic outside controllers |
| Versioning | Make API versions easier to manage |
Prerequisites
Before creating Laravel API Resources, you should have a Laravel application with an Eloquent model.
For example:
<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
protected $fillable = [
'name',
'email',
];
}
You should also have some basic understanding of:
- Laravel routing
- Controllers
- Eloquent models
- REST APIs
- JSON responses
How to Create an API Resource in Laravel
Laravel provides an Artisan command for creating API Resources.
Run:
php artisan make:resource UserResource
Laravel will create:
app/
└── Http/
└── Resources/
└── UserResource.php
The generated Resource typically looks like:
<?php
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 parent::toArray($request);
}
}
The toArray() method determines what data is returned by the API.
Creating Your First Laravel API Resource
Let’s create a simple UserResource.
<?php
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,
];
}
}
Now the API Resource exposes only these three fields.
Returning an API Resource From a Controller
Suppose your controller retrieves a user:
<?php
namespace App\Http\Controllers;
use App\Models\User;
class UserController extends Controller
{
public function show(int $id)
{
$user = User::findOrFail($id);
return new UserResource($user);
}
}
Don’t forget to import the Resource:
use App\Http\Resources\UserResource;
The complete controller becomes:
<?php
namespace App\Http\Controllers;
use App\Http\Resources\UserResource;
use App\Models\User;
class UserController extends Controller
{
public function show(int $id)
{
$user = User::findOrFail($id);
return new UserResource($user);
}
}
API Resource Response Example
The API might return:
{
"data": {
"id": 1,
"name": "John Doe",
"email": "john@example.com"
}
}
Notice that Laravel wraps the Resource inside a data property.
This is the default behavior for Laravel JSON Resources.
API Resources vs Returning Models Directly
You could return the model directly:
return User::findOrFail($id);
But using a Resource gives you more control:
return new UserResource(
User::findOrFail($id)
);
Comparison
| Approach | Control | Recommended for APIs |
|---|---|---|
| Return model directly | Low | Sometimes |
response()->json() | Medium | Yes |
| API Resource | High | Yes |
For production APIs, API Resources are often a better choice because the response structure is explicitly defined.
Creating a Resource Collection
When returning multiple models, use a Resource collection.
Suppose you want to return all users:
public function index()
{
$users = User::latest()->get();
return UserResource::collection($users);
}
The response looks like:
{
"data": [
{
"id": 1,
"name": "John Doe",
"email": "john@example.com"
},
{
"id": 2,
"name": "Jane Smith",
"email": "jane@example.com"
}
]
}
This keeps individual and collection responses consistent.
Laravel API Resources With Pagination
Pagination is extremely common in REST APIs.
Instead of retrieving every record:
$users = User::all();
use:
$users = User::latest()->paginate(20);
return UserResource::collection($users);
Laravel can include pagination information in the response.
A simplified response may look like:
{
"data": [
{
"id": 1,
"name": "John Doe"
},
{
"id": 2,
"name": "Jane Smith"
}
],
"links": {
"first": "/api/users?page=1",
"last": "/api/users?page=10",
"next": "/api/users?page=2"
},
"meta": {
"current_page": 1,
"per_page": 20,
"total": 200
}
}
This is particularly useful for mobile applications and frontend applications where loading hundreds of records at once would be inefficient.
Formatting Data With Laravel API Resources
One of the biggest advantages of API Resources is that you can transform data before returning it.
For example, format a date:
public function toArray(Request $request): array
{
return [
'id' => $this->id,
'name' => $this->name,
'created_at' => $this->created_at?->format('Y-m-d H:i:s'),
];
}
Instead of exposing Laravel’s raw date representation, your API now returns:
{
"id": 1,
"name": "John Doe",
"created_at": "2026-08-24 10:30:00"
}
Renaming API Fields
You don’t have to use the same names as your database columns.
For example, your database may contain:
first_name
last_name
But your API might return:
{
"firstName": "John",
"lastName": "Doe"
}
The Resource can handle this transformation:
public function toArray(Request $request): array
{
return [
'id' => $this->id,
'firstName' => $this->first_name,
'lastName' => $this->last_name,
];
}
This allows your database schema and API contract to evolve independently.
Adding Computed Fields
API Resources can also return calculated values that don’t exist directly in the database.
For example:
public function toArray(Request $request): array
{
return [
'id' => $this->id,
'name' => $this->name,
'full_name' => $this->first_name . ' ' . $this->last_name,
];
}
The API can return:
{
"id": 1,
"name": "John",
"full_name": "John Doe"
}
This is useful for presentation-oriented values.
Laravel API Resources With Relationships
Suppose a user has many orders.
Your model might contain:
public function orders()
{
return $this->hasMany(Order::class);
}
Create an OrderResource:
php artisan make:resource OrderResource
Then define it:
<?php
namespace App\Http\Resources;
use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;
class OrderResource extends JsonResource
{
public function toArray(Request $request): array
{
return [
'id' => $this->id,
'total' => $this->total,
'status' => $this->status,
];
}
}
Now include orders in UserResource:
public function toArray(Request $request): array
{
return [
'id' => $this->id,
'name' => $this->name,
'email' => $this->email,
'orders' => OrderResource::collection(
$this->whenLoaded('orders')
),
];
}
The whenLoaded() method is important because it helps prevent the Resource from automatically triggering an unexpected relationship query.
Eager Loading Relationships
When using relationships inside API Resources, eager load the required relationships in your controller.
For example:
public function show(int $id)
{
$user = User::with('orders')
->findOrFail($id);
return new UserResource($user);
}
This is generally better than repeatedly querying the database for every user.
Avoid the N+1 Problem
Without proper eager loading, an API could potentially execute:
1 query → users
+ 1 query → orders for user 1
+ 1 query → orders for user 2
+ 1 query → orders for user 3
...
With eager loading:
1 query → users
1 query → orders
This can significantly improve API performance.
Conditional Relationships
Sometimes you only want to return relationships when they have been loaded.
Use:
'orders' => OrderResource::collection(
$this->whenLoaded('orders')
),
This gives the controller control over which relationships are included.
For example:
$user = User::with('orders')->findOrFail($id);
will include orders.
While:
$user = User::findOrFail($id);
does not automatically require the Resource to load them.
Conditional Fields in API Resources
Sometimes a field should only be returned when a certain condition is met.
For example, an admin may see additional information.
Laravel provides when() for conditional attributes.
public function toArray(Request $request): array
{
return [
'id' => $this->id,
'name' => $this->name,
'internal_notes' => $this->when(
$request->user()?->isAdmin(),
$this->internal_notes
),
];
}
This allows the same Resource to support different API consumers.
Conditional Fields Based on Authentication
You can also expose information depending on the authenticated user.
For example:
'is_owner' => $this->when(
$request->user()?->id === $this->id,
true
),
The response could contain:
{
"id": 10,
"name": "John Doe",
"is_owner": true
}
This can be useful for frontend applications that need to determine what actions a user can perform.
Laravel API Resources With Nested Resources
For more complex APIs, you can create multiple Resources.
For example:
UserResource
│
├── OrderResource
│ │
│ └── ProductResource
│
└── AddressResource
Example:
return [
'id' => $this->id,
'name' => $this->name,
'address' => new AddressResource(
$this->whenLoaded('address')
),
'orders' => OrderResource::collection(
$this->whenLoaded('orders')
),
];
This keeps each transformation focused on its own model.
Creating a Custom Resource Collection
For more advanced APIs, you may want custom collection behavior.
Create a collection:
php artisan make:resource UserCollection
Laravel generates:
app/Http/Resources/UserCollection.php
You can then customize the response.
<?php
namespace App\Http\Resources;
use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\ResourceCollection;
class UserCollection extends ResourceCollection
{
public function toArray(Request $request): array
{
return [
'data' => $this->collection,
'status' => 'success',
];
}
}
Custom collections can be useful when your API requires additional collection-level metadata.
Adding Meta Information
Sometimes an API needs to return additional information alongside the resource.
For example:
return (new UserResource($user))
->additional([
'meta' => [
'api_version' => 'v1',
],
]);
The response can contain:
{
"data": {
"id": 1,
"name": "John Doe"
},
"meta": {
"api_version": "v1"
}
}
This is useful for API metadata, version information, or other non-resource information.
Adding Links to API Resources
API Resources can also include links.
For example:
public function with(Request $request): array
{
return [
'links' => [
'documentation' => '/api/docs',
],
];
}
Depending on your API design, links can help clients discover related resources or documentation.
Real-World Example: Product API
Let’s create a practical Product API Resource.
Assume the products table contains:
id
name
description
price
stock
category_id
created_at
updated_at
Create the Resource:
php artisan make:resource ProductResource
Then:
<?php
namespace App\Http\Resources;
use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;
class ProductResource extends JsonResource
{
public function toArray(Request $request): array
{
return [
'id' => $this->id,
'name' => $this->name,
'description' => $this->description,
'price' => (float) $this->price,
'stock' => $this->stock,
'category' => new CategoryResource(
$this->whenLoaded('category')
),
'created_at' => $this->created_at?->format(
'Y-m-d H:i:s'
),
];
}
}
Now the controller can return:
public function show(int $id)
{
$product = Product::with('category')
->findOrFail($id);
return new ProductResource($product);
}
The API response could look like:
{
"data": {
"id": 101,
"name": "Wireless Headphones",
"description": "Noise-cancelling wireless headphones",
"price": 149.99,
"stock": 25,
"category": {
"id": 5,
"name": "Electronics"
},
"created_at": "2026-08-24 10:30:00"
}
}
This is much cleaner than exposing the complete Eloquent model.
API Resource for a RESTful Controller
A typical controller can use Resources for all CRUD operations.
<?php
namespace App\Http\Controllers;
use App\Http\Resources\ProductResource;
use App\Models\Product;
use Illuminate\Http\Request;
class ProductController extends Controller
{
public function index()
{
$products = Product::latest()
->paginate(20);
return ProductResource::collection($products);
}
public function show(int $id)
{
$product = Product::findOrFail($id);
return new ProductResource($product);
}
}
Your routes might look like:
use App\Http\Controllers\ProductController;
Route::get('/products', [
ProductController::class,
'index'
]);
Route::get('/products/{id}', [
ProductController::class,
'show'
]);
The architecture becomes:
GET /api/products
↓
ProductController
↓
Product Model
↓
ProductResource
↓
JSON Response
API Resources and API Versioning
API Resources can also help when maintaining multiple API versions.
For example:
app/
└── Http/
└── Resources/
├── V1/
│ └── UserResource.php
│
└── V2/
└── UserResource.php
You might have:
App\Http\Resources\V1\UserResource
and:
App\Http\Resources\V2\UserResource
This makes it possible to evolve your API without immediately breaking existing clients.
For example, version 1 might return:
{
"id": 1,
"name": "John Doe"
}
while version 2 could return:
{
"id": 1,
"full_name": "John Doe",
"profile": {
"email": "john@example.com"
}
}
Common Mistakes When Using Laravel API Resources
1. Returning Sensitive Fields
Avoid exposing fields such as:
password
remember_token
private_notes
internal_flags
unless there is a specific reason to return them.
Explicitly define the fields you want to expose.
2. Loading Too Many Relationships
Don’t eager load every relationship just because it is available.
Instead of:
User::with([
'orders',
'orders.products',
'address',
'roles',
'permissions',
'notifications'
])->get();
only load relationships required by the endpoint.
3. Ignoring the N+1 Problem
If a Resource accesses relationships repeatedly, make sure those relationships are properly eager loaded.
Use:
User::with('orders')->get();
and:
$this->whenLoaded('orders')
where appropriate.
4. Putting Business Logic in Resources
Resources should primarily transform data.
Avoid turning them into large business-logic classes.
Bad:
public function toArray(Request $request): array
{
// Complex payment processing
// Database updates
// Email sending
// Business calculations
}
A Resource should generally focus on representing data.
5. Returning Database Structure Unnecessarily
Your database schema does not have to be your API schema.
For example:
Database:
user_first_name
user_last_name
Your API could expose:
{
"firstName": "John",
"lastName": "Doe"
}
Resources provide the transformation layer needed to make this possible.
Laravel API Resource Best Practices
1. Explicitly Define API Fields
Prefer:
return [
'id' => $this->id,
'name' => $this->name,
'email' => $this->email,
];
rather than exposing an entire model without considering what clients actually need.
2. Use Dedicated Resources for Relationships
For example:
UserResource
OrderResource
ProductResource
CategoryResource
This makes nested API responses easier to maintain.
3. Use whenLoaded() for Relationships
For example:
'orders' => OrderResource::collection(
$this->whenLoaded('orders')
),
This provides better control over relationship loading.
4. Use Pagination for Large Collections
Instead of:
Product::all();
prefer:
Product::paginate(20);
when returning potentially large datasets.
5. Keep Resources Focused
A Resource should answer one primary question:
“How should this model be represented in this API response?”
Avoid putting unrelated application logic inside it.
6. Think About API Versioning Early
If your application is expected to have long-term API consumers, organizing Resources by API version can make future changes easier.
Laravel API Resources vs API Transformers
Before Laravel introduced its modern Resource system, many PHP applications used custom transformer classes.
A simplified transformer might look like:
class UserTransformer
{
public function transform(User $user): array
{
return [
'id' => $user->id,
'name' => $user->name,
];
}
}
Laravel API Resources provide a framework-native approach to the same general problem.
| Feature | Custom Transformer | Laravel API Resource |
|---|---|---|
| Laravel integration | Low | High |
| Pagination support | Manual | Built-in |
| Relationship handling | Manual | Built-in |
| Conditional fields | Manual | Built-in |
| Consistent JSON responses | Depends on implementation | Supported |
| Maintenance | Depends on project | Generally simpler |
For Laravel applications, API Resources are usually a natural choice.
A Practical Laravel API Resource Architecture
For a medium-sized Laravel API, you might organize your application like this:
app/
│
├── Http/
│ ├── Controllers/
│ │ └── ProductController.php
│ │
│ └── Resources/
│ ├── ProductResource.php
│ ├── CategoryResource.php
│ └── OrderResource.php
│
├── Models/
│ ├── Product.php
│ ├── Category.php
│ └── Order.php
│
└── Services/
└── ProductService.php
The responsibilities are separated:
Controller
│
│ Handles HTTP request
▼
Service
│
│ Handles business logic
▼
Model
│
│ Handles database interaction
▼
Resource
│
│ Transforms output
▼
JSON API Response
This separation becomes increasingly valuable as the application grows.
Key Takeaways
Here are the most important points to remember about Laravel API Resources:
- API Resources transform Eloquent models into API-friendly JSON.
- Create a Resource using
php artisan make:resource. - Define the API response inside
toArray(). - Use
Resource::collection()for multiple records. - Use pagination for large datasets.
- Use
whenLoaded()for relationships. - Use
when()for conditional fields. - Use dedicated Resources for nested relationships.
- Avoid exposing sensitive model attributes.
- Keep business logic out of Resources.
- Use eager loading to prevent N+1 query problems.
- Consider Resource versioning for long-term APIs.
Frequently Asked Questions
What is an API Resource in Laravel?
A Laravel API Resource is a transformation layer that converts Eloquent models into structured JSON responses. It allows developers to control which fields and relationships are returned by an API.
How do I create an API Resource in Laravel?
Use Laravel’s Artisan command:
php artisan make:resource UserResource
The Resource will be created inside:
app/Http/Resources/
You can then define the response structure inside the toArray() method.
How do I return a Laravel API Resource?
For a single model, use:
return new UserResource($user);
For a collection, use:
return UserResource::collection($users);
Can Laravel API Resources handle relationships?
Yes. Laravel API Resources can transform relationships using other Resources.
For example:
'orders' => OrderResource::collection(
$this->whenLoaded('orders')
),
Using whenLoaded() also helps ensure the relationship is only included when it has been loaded.
Should I use API Resources instead of returning Eloquent models?
For many production APIs, API Resources are preferable because they provide explicit control over the API response. They help prevent accidental exposure of database fields and make response structures easier to maintain.
How do I paginate Laravel API Resources?
Use Laravel’s pagination methods:
$users = User::paginate(20);
return UserResource::collection($users);
Laravel will include pagination metadata and links in the response.
Can API Resources rename database fields?
Yes. A Resource can map database fields to completely different API field names.
return [
'firstName' => $this->first_name,
'lastName' => $this->last_name,
];
Do Laravel API Resources improve API security?
They can improve data exposure control by allowing you to explicitly choose which model attributes are returned. However, Resources are not a replacement for authentication, authorization, validation, or other security mechanisms.
Conclusion
Laravel API Resources provide a clean and maintainable way to transform Eloquent models into JSON responses.
Instead of allowing your database structure to directly determine your API structure, Resources give you a dedicated layer where you can control fields, rename attributes, format dates, transform relationships, add calculated values, and conditionally expose information.
For simple APIs, a Resource may initially seem like an extra layer. But as your Laravel application grows, that separation becomes increasingly valuable.
A well-designed API can follow a simple flow:
Request
↓
Controller
↓
Service / Business Logic
↓
Eloquent Model
↓
API Resource
↓
JSON Response
By using Laravel API Resources consistently, you can build APIs that are easier to maintain, safer to expose, and more predictable for frontend and mobile clients.
Whether you’re building an eCommerce platform, booking system, SaaS application, CRM, or mobile backend, learning how to create and structure Laravel API Resources is an important skill for modern Laravel development.
