Typed Fields, Metrics, and OpenAPI Docs

Gautier Deleglise simply launched Laravel Relaxation Api 3.0, a rebuild of the bundle that turns your Eloquent fashions right into a REST API from a single useful resource class. We first lined it when it launched in 2023 and once more when it added Laravel Scout help. Model 3.0 retains the identical thought and replaces most of what sits beneath it.

A number of the highlights embrace:

• Typed fields that drive filters, validation, response values, and the API docs
• OpenAPI documentation by way of Scramble
• Metric endpoints for counts, traits, partitions, progress, and tables
• Confirmations for actions and bulk writes, utilizing a 428 response and a signed token

#Typed Fields

In 2.x, a useful resource listed column names. In 3.0, a useful resource declares typed fields with Textual content, Integer, Quantity, Date, Enum, Json, and extra:

public perform fields(): array
{
    return [
        ID::make('id'),
        Text::make('title')->rules('max:80')->creationRules('required'),
        Integer::make('seats')->rules('min:0'),
        Enum::make('status', ShowStatus::class)->offered([ShowStatus::Planned, ShowStatus::OnSale]),
        Date::make('starts_on')->creationRules('required'),
    ];
}

The bundle makes use of that one declaration for the remainder of the API:

• Filters solely settle for operators that match the sector’s kind. The rest returns a 422.
• Writes are validated in opposition to the sector’s guidelines, and errors level on the actual key that failed, similar to mutate.0.attributes.seats.
• Responses return values of their kind, so numbers come again as numbers and an empty JSON discipline comes again as {}.
• Enum::provided() limits which instances a shopper can write. Within the instance above, a withdrawn standing remains to be readable and filterable on outdated rows, however no person can set it once more.

#OpenAPI Docs By way of Scramble

The built-in documentation generator is gone. Model 3.0 integrates with Scramble as an alternative. As soon as you put in Scramble, /docs/api paperwork each endpoint of each useful resource, with a typed physique per useful resource, the foundations for every discipline, request examples, and error responses.

The bundle’s personal check suite sends these request examples to the API and validates every response in opposition to the generated doc. If the docs and the API ever disagree, a check fails.

#Metrics

Metrics are new in 3.0. You declare a metric on a useful resource, and it will get its personal route with no controller code. Here’s a partition that counts reveals by standing:

class ShowsByStatus extends Partition
{
    public perform calculate(Builder $question): PartitionResult
    {
        return $this->rely($question, 'standing');
    }
}

The endpoint returns every group with its rely:

{"information": {"kind": "partition", "elements": [{"key": "planned", "label": "planned", "value": 2}, {"key": "sold_out", "label": "sold_out", "value": 1}], "different": null}}

The Worth, Development, Partition, Progress, and Desk metric sorts cowl counts, sums, averages, medians, and percentiles. Additionally they help date ranges, time zones, a comparability with the earlier interval, and a consequence cache. A metric solely counts the rows the present consumer is allowed to see, and the shopper can slim it additional with the identical filters it makes use of for search.

#Confirmations

An motion, a mutate, a destroy, a restore, or a drive destroy can now ask the consumer to substantiate earlier than it runs. This works nicely for bulk cancellations and deletions:

public perform destroyConfirmation(Assortment $fashions): ?Affirmation
{
    return Affirmation::make("Delete {$models->rely()} reveals and their tickets?");
}

The endpoint responds with a 428 standing, your message, and a signed token. When the shopper sends the identical request again with that token, it runs. There isn’t any session concerned and no further endpoint to name.

#Different Modifications

• Insurance policies run on each useful resource a request reaches and on each row it writes, earlier than the primary write occurs. perimeterQuery() scopes every useful resource to a tenant or group at each stage of a search.
• A single write can create, replace, connect, sync, and delete youngster rows in a single transaction. A response block returns the written rows, and assets marked versioned() return a 409 when a row modified after the shopper learn it.
• Actions can run in a single transaction per run, per chunk, or per row, with queued chunks and batches that report progress.
• Relaxation::search() replays a saved search exterior of HTTP, so a job or an export goes by way of the identical guidelines and insurance policies because the API.
• Textual content search works with LIKE, MySQL, MariaDB, or PostgreSQL full-text indexes, or Meilisearch, Typesense, and Algolia by way of Scout.
• Each client-facing message ships in English and French and follows the request locale.
• php artisan relaxation:quick-start reads your tables and generates assets, controllers, starter insurance policies, and routes. php artisan relaxation:verify catches a lacking coverage or perimeter in CI.
• The bundle ships a Laravel Increase talent, so your AI assistant writes assets the way in which the bundle expects.

#Improve Notes

Laravel Relaxation Api 3.0 requires PHP 8.3+ and Laravel 13.30+. Functions on Laravel 12 ought to keep on 2.x.

composer require lomkit/laravel-rest-api:^3.0

Model 3.0 has breaking adjustments throughout the bundle, and the improve information walks by way of each, space by space.

#References