Laravel JSON:API Documentation

Schemas are the core of Laravel JSON:API. They define how your Eloquent models are exposed via the API. You define fields (including relationships), filters, and pagination within a class extending Schema.

Key components of a schema include:

• $model: The Eloquent model class this schema represents.
• fields(): An array of field definitions using types like ID, Str, DateTime, BelongsTo, HasMany, and BelongsToMany.
• filters(): An array of available filters (e.g., WhereIdIn, WhereIn).
• pagination(): Defines the pagination strategy (e.g., PagePagination).

class PostSchema extends Schema
{
    /**
     * The model the schema corresponds to.
     *
     * @var string
     */
    public static string $model = Post::class;

    /**
     * The maximum include path depth.
     *
     * @var int
     */
    protected int $maxDepth = 3;

    /**
     * Get the resource fields.
     *
     * @return array
     */
    public function fields(): array
    {
        return [
            ID::make(),
            BelongsTo::make('author')->type('users')->readOnly(),
            HasMany::make('comments')->readOnly(),
            Str::make('content'),
            DateTime::make('createdAt')->sortable()->readOnly(),
            DateTime::make('publishedAt')->sortable(),
            Str::make('slug'),
            BelongsToMany::make('tags'),
            Str::make('title')->sortable(),
            DateTime::make('updatedAt')->sortable()->readOnly(),
        ];
    }

    /**
     * Get the resource filters.
     *
     * @return array
     */
    public function filters(): array
    {
        return [
            WhereIdIn::make($this),
            WhereIn::make('author', 'author_id'),
        ];
    }

    /**
     * Get the resource paginator.
     *
     * @return Paginator|null
     */
    public function pagination(): ?Paginator
    {
        return PagePagination::make();
    }
}

When building custom validation or authorization logic for JSON:API endpoints, extend LaravelJsonApi\Laravel\Http\Requests\FormRequest instead of the standard Laravel BaseFormRequest. This specialized class provides helper methods to detect JSON:API media types and determine the specific JSON:API action being performed (e.g., viewing a relationship, updating a resource, or attaching to a relationship).

Key capabilities include:

• Media Type Detection: Methods like isJsonApi(), wantsJsonApi(), and acceptsJsonApi() check for the application/vnd.api+json content type.
• Action Detection: Methods like isCreating(), isUpdating(), isViewingRelated(), and isAttachingRelationship() allow you to branch logic based on the JSON:API request intent.
• Schema Access: The schema() method provides direct access to the Schema instance associated with the current route.
• Relationship Context: getFieldName() returns the name of the relationship if the request is targeting a relationship endpoint.

<?php

namespace App\Http\Requests;

use LaravelJsonApi\Laravel\Http\Requests\FormRequest;

class CreatePostRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'title' => 'required|string',
        ];
    }
}

The middleware() method allows you to apply middleware to your resource routes. It supports two modes:

1. Global Middleware: Pass a simple array or list of strings to apply middleware to all routes generated for the resource.
2. Action-Specific Middleware: Pass an associative array where the key * represents middleware applied to all actions, and other keys represent middleware applied to specific actions.

You can also use withoutMiddleware(...$middleware) to explicitly remove specific middleware from the resource routes.

// Apply middleware to all resource routes
$router->resource('articles')->middleware('auth:api');

// Apply specific middleware to all actions and others to specific ones
$router->resource('articles')->middleware([
    '*' => ['web'],
    'store' => ['throttle:60,1'],
]);

// Remove middleware
$router->resource('articles')->withoutMiddleware('guest');

When registering a resource in Laravel JSON:API, you can use the fluent API provided by PendingResourceRegistration to customize the generated routes. This allows you to filter which controller methods are exposed, set custom route names, override parameters, and manage middleware.

Common customization tasks include:

• Filtering actions: Use only() to specify which methods to include or except() to exclude specific ones. Use readOnly() as a shortcut for only('index', 'show').
• Naming routes: Use name() to set a specific name for a method, or names() to set multiple names at once. Note that certain aliases are mapped: create maps to store, read maps to show, and delete maps to destroy.
• Parameter customization: Use parameter() to change the route parameter name.
• Middleware management: Use middleware() to add middleware (either globally for all resource routes or specifically for actions using the * key) and withoutMiddleware() to exclude specific middleware.
• Relationships and Actions: Use relationships() to define relationship-specific routes via a callback, and actions() to define custom resource actions.

$router->resource('articles')
    ->only(['index', 'show'])
    ->middleware('auth:api')
    ->parameter('article')
    ->register();

The ActionRegistrar provides a fluent API for defining custom HTTP routes for a specific JSON:API resource. It handles URI normalization, controller action guessing, and automatic parameter injection (like resource IDs).

Key Features

• HTTP Method Helpers: Use get(), post(), patch(), put(), delete(), and options() to register routes.
• ID-based Routes: By default, routes are registered relative to the resource collection. Calling withId() tells the registrar to include the resource's ID parameter in the URI (e.g., /{id}/your-action).
• Automatic Action Guessing: If no specific controller action is provided, the registrar converts the URI segment into a camelCase string to use as the method name on your controller.
• Parameter Management: When withId() is used, the registrar automatically resolves the correct resource parameter name based on your resource configuration.

// Example of registering a custom action on a resource
$resource->get('publish', 'publishAction') // GET /articles/publish
    ->withId()                             // GET /articles/{id}/publish
    ->post('archive');                    // POST /articles/{id}/archive