REST API with Laravel and API Resources

A mobile app, a React front end or a partner consumes your data as JSON through an API. Laravel makes this very simple, provided you control what you expose.

Enabling API routes

Since Laravel 11, the skeleton no longer contains routes/api.php. You add it with:

php artisan install:api

This command creates routes/api.php (all its routes are prefixed with /api) and installs Laravel Sanctum, used in the next lesson.

// routes/api.php
use App\Http\Controllers\Api\ProductController;

Route::apiResource('products', ProductController::class);
// GET /api/products, POST /api/products, GET|PUT|PATCH|DELETE /api/products/{product}

API Resources

Returning Product::all() would expose all columns, including internal fields, and would tie your JSON format to the database schema. An API Resource explicitly describes the public representation:

php artisan make:resource ProductResource

class ProductResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id'        => $this->id,
            'nom'       => $this->nom,
            'prix'      => $this->prix_centimes / 100,         // format suited to the client
            'en_stock'  => $this->stock > 0,
            'categorie' => new CategoryResource($this->whenLoaded('category')),
            'cree_le'   => $this->created_at->toIso8601String(),
        ];
    }
}

whenLoaded('category') only includes the category if it was loaded with with('category'): the resource never triggers an extra query behind your back.

The API controller

class ProductController extends Controller
{
    public function index()
    {
        return ProductResource::collection(
            Product::with('category')->latest()->paginate(20)
        );   // { "data": [...], "links": {...}, "meta": {...} }
    }

    public function store(StoreProductRequest $request)
    {
        $product = Product::create($request->validated());
        return (new ProductResource($product))->response()->setStatusCode(201);
    }

    public function show(Product $product)
    {
        return new ProductResource($product->load('category'));
    }

    public function destroy(Product $product)
    {
        $product->delete();
        return response()->noContent();   // 204
    }
}

A paginated collection automatically produces three keys: data (the items), links (first, last, prev, next) and meta (current_page, last_page, per_page, total…).

Status codes and errors

Situation	Code
Successful read	200
Creation	201
Deletion with no content	204
Unauthenticated / forbidden	401 / 403
Missing resource	404
Validation failed	422

In a Laravel 13 project, bootstrap/app.php already asks to render api/* route exceptions as JSON ($exceptions->shouldRenderJsonWhen(...)): a validation error there produces a 422 JSON response. The client must still send the Accept: application/json header: without it, the authentication middleware tries to redirect an unauthenticated client to a login route instead of responding 401. Validation errors take the form {"message": "...", "errors": {"nom": ["..."]}}.

Test quickly with curl:

curl -s -H "Accept: application/json" http://127.0.0.1:8000/api/products?page=2

In summary: dedicated API routes, explicit resources, deliberately loaded relationships and correct HTTP codes. This is what makes an API predictable for those who consume it.