How to Use API Resource in Laravel: Simple Guide

In Laravel, use API Resources to transform your models into JSON responses by creating resource classes with php artisan make:resource. Then return these resources from your controller methods to format the output cleanly and consistently.

Syntax

An API Resource class extends Illuminate\Http\Resources\Json\JsonResource and defines a toArray() method to specify how to convert a model into an array for JSON output.

In your controller, return the resource instance or a collection of resources to send formatted JSON responses.

php

use Illuminate\Http\Resources\Json\JsonResource;

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

// In Controller
use App\Http\Resources\UserResource;

public function show($id)
{
    $user = User::findOrFail($id);
    return new UserResource($user);
}

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

Example

This example shows how to create a UserResource and use it in a controller to return a single user and a list of users as JSON with only selected fields.

php

<?php

namespace App\Http\Resources;

use Illuminate\Http\Resources\Json\JsonResource;

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

// Controller
namespace App\Http\Controllers;

use App\Models\User;
use App\Http\Resources\UserResource;

class UserController extends Controller
{
    public function show($id)
    {
        $user = User::findOrFail($id);
        return new UserResource($user);
    }

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

Output

{
  "id": 1,
  "name": "John Doe",
  "email": "[e-mail]"
}

[
  {
    "id": 1,
    "name": "John Doe",
    "email": "[e-mail]"
  },
  {
    "id": 2,
    "name": "Jane Smith",
    "email": "[e-mail]"
  }
]

Common Pitfalls

• Not returning the resource instance from the controller, instead returning the model directly, which skips formatting.
• Forgetting to import the resource class in the controller.
• Using return UserResource::collection($users); for multiple models but returning a single model instance without wrapping it in new UserResource().
• Modifying the model directly instead of using the resource for output formatting.

php

<?php
// Wrong: returning model directly
public function show($id)
{
    $user = User::findOrFail($id);
    return $user; // No formatting
}

// Right: returning resource
public function show($id)
{
    $user = User::findOrFail($id);
    return new UserResource($user);
}

Quick Reference

API Resource Usage Cheat Sheet:

• Create resource: php artisan make:resource ResourceName
• Define toArray() to format output
• Return single resource: return new ResourceName($model);
• Return collection: return ResourceName::collection($models);
• Use resources to keep API responses consistent and clean

Key Takeaways

Use Laravel API Resources to format model data into clean JSON responses.

Create resource classes with artisan and define the toArray method for output.

Return resource instances or collections from controllers for consistent API output.

Avoid returning raw models directly to keep your API responses structured.

Import resource classes properly and use collection method for multiple models.