How to use API resources in Laravel?

Using API resources is the recommended way to return structured JSON responses when building RESTful APIs in Laravel. 1. Use php artisan make:resource PostResource to create resource class; 2. Define return fields in the toArray method, such as id, title, created_at, etc.; 3. Return new PostResource($post) or PostResource::collection($posts); 4. Handle nested relationships through new UserResource($this->whenLoaded('user')); 5. Use the $this->when() condition to include fields to avoid returning null; 6. Add metadata through the additional() method, such as paging information; 7. Follow best practices, including preloading relationships, avoiding N 1 queries, and keeping resource logic concise. In this way, Laravel can automatically generate consistent and maintainable JSON responses, improve the readability and performance of the API, and ultimately achieve efficient data output.

Using API resources in Laravel is a clean and efficient way to transform your models and collections into JSON responses, especially when building RESTful APIs. Laravel's API resources help you control exactly what data is returned and how it's structured, making your responses consistent and maintainable.

Here's how to use API resources in Laravel:

1. Create an API Resource

First, generate a resource using Artisan. For a Post model, run:

 php artisan make:resource PostResource

This creates a PostResource class in the app/Http/Resources directory.

If you're working with a collection (eg, list of posts), Laravel also provides a way to handle that automatically.

You can also create a resource collection:

 php artisan make:resource PostCollection

But as of Laravel 8 , ResourceCollection is built into the base resource, so you usually just need one resource class.

2. Define the Resource Structure

Open app/Http/Resources/PostResource.php . The toArray method defines what data is included in the response.

 <?php

namespace App\Http\Resources;

use Illuminate\Http\Resources\Json\JsonResource;

class PostResource extends JsonResource
{
    public function toArray($request)
    {
        Return [
            &#39;id&#39; => $this->id,
            &#39;title&#39; => $this->title,
            &#39;content&#39; => $this->content,
            &#39;created_at&#39; => $this->created_at->format(&#39;Ymd H:i:s&#39;),
            &#39;author&#39; => $this->whenLoaded(&#39;user&#39;, function () {
                return new UserResource($this->user);
            }),
        ];
    }
}

? Use $this->whenLoaded() to conditionally include relationships only if they're already loaded (to avoid N 1 queries).

3. Use the Resource in a Controller

In your controller, wrap the model or collection with the resource:

 use App\Http\Resources\PostResource;
use App\Models\Post;

// Return a single post
public function show(Post $post)
{
    return new PostResource($post);
}

// Return a list of posts
public function index()
{
    return PostResource::collection(Post::with('user')->get());
}

Or with pagination (common in APIs):

 public function index()
{
    return PostResource::collection(Post::paginate(10));
}

Laravel automatically handles the pagination structure.

4. Working with Relationships (Nested Resources)

If your post has a user, create a UserResource :

 php artisan make:resource UserResource

Then use it inside PostResource :

 'author' => new UserResource($this->whenLoaded('user')),

This keeps your response structured and reusable.

5. Conditional Attributes

Use when() to include fields conditionally:

 'published_at' => $this->when(!empty($this->published_at), $this->published_at),
'views' => $this->when($this->resource->relationLoaded('stats'), $this->views),

This avoids sending null values when data isn't relevant.

6. Customize the Top-Level Response (Resource Collection)

If you want to customize the wrapper (eg, add meta data), override the toResponse method or use an anonymous resource collection.

For example, in a controller:

 use Illuminate\Http\Resources\Json\AnonymousResourceCollection;

public function index(): AnonymousResourceCollection
{
    $posts = Post::paginate(10);

    return PostResource::collection($posts)->additional([
        'meta' => [
            'total_pages' => $posts->lastPage(),
            'current_page' => $posts->currentPage(),
        ],
    ]);
}

This adds extra info without creating a new resource class.

7. Best Practices

• Always eager load relationships used in resources to avoid performance issues.
• Use whenLoaded() for optional relationships.
• Keep resource logic simple — don't put business logic inside.
• Use different resources for different API versions if needed (eg, V1\PostResource ).

Using API resources in Laravel makes your API responses predictable and easy to maintain. You get full control over the output, and Laravel handles the JSON structure and status codes automatically.

Basically, wrap your models in resources, define the toArray() method, and return them from controllers — that's it.

The above is the detailed content of How to use API resources in Laravel?. For more information, please follow other related articles on the PHP Chinese website!