Skip to content
Projects

Lomkit/laravel-rest-api

View on GitHub

Lomkit/laravel-rest-api has 651 GitHub stars and 35 forks. GitHot measured +10 stars in 24 hours. Last checked 2026-11-16 19:02 UTC. Last push 2026-11-15.

How these counts are measured

Measured star growth

in 24h
+10
in 7 days
Collecting history
in 15 days
Collecting history
in 1 month
Collecting history

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

Describe a model, get a full API: search, writes, actions and metrics for your Eloquent models, checked against your policies and documented with OpenAPI.

Developer Tools

README.md

Original

Laravel Rest Api: one resource class, a complete REST API for your Eloquent models

Tests Code quality Latest version Total downloads License

Documentation · Upgrade from 2.x

Laravel Rest Api

Describe a model once. Get a complete API.

Write one resource class for an Eloquent model. Laravel Rest Api turns it into search, mutate, action, metric, details and delete endpoints. Your policies authorize every request, your frontend gets a rich query language, and Scramble gets a typed OpenAPI document.

No controller methods to write, no query parsing to maintain.

  • One class, every endpoint: search, batch writes, custom actions, metrics, soft deletes.
  • A search grammar for filters, nested groups, relations, scopes, includes, aggregates and text search.
  • Laravel policies everywhere: every resource a request reaches, every row it writes.
  • Built for frontends: a details endpoint, per-row abilities, Precognition, precise 422 messages.
  • Documented for you: an OpenAPI document with typed schemas and examples, through Scramble.

Documentation

The full guide lives on the documentation site: installation, every endpoint, configuration and recipes. Coming from 2.x? Read the upgrade guide.

For AI assistants, the site serves llms.txt and llms-full.txt, and the package ships a Laravel Boost skill: see Use with AI.

Requirements

PHP 8.3+ and Laravel 13.30+.

From model to API

Take a Show model with a stage() relation and an artists() relation whose pivot holds a role.

1. Install the package.

composer require lomkit/laravel-rest-api

2. Describe what the API exposes. Only what you declare exists for the client. php artisan rest:resource ShowResource --model=Show scaffolds the class, and StageResource and ArtistResource follow the same pattern.

namespace App\Rest\Resources;

use App\Models\Show;
use Lomkit\Rest\Fields\Date;
use Lomkit\Rest\Fields\ID;
use Lomkit\Rest\Fields\Integer;
use Lomkit\Rest\Fields\Text;
use Lomkit\Rest\Relations\BelongsTo;
use Lomkit\Rest\Relations\BelongsToMany;

class ShowResource extends Resource
{
    public static string $model = Show::class;

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

    public function relations(): array
    {
        return [
            BelongsTo::make('stage', StageResource::class),
            BelongsToMany::make('artists', ArtistResource::class)
                ->pivotFields([Text::make('role')->nullable()]),
        ];
    }
}

3. Bind it to a route. The controller is one line, and your ShowPolicy authorizes every request (php artisan rest:policy ShowPolicy --model=Show writes a starting point).

class ShowsController extends Controller
{
    public static string $resource = ShowResource::class;
}
// routes/api.php
use App\Rest\Controllers\ShowsController;
use Lomkit\Rest\Facades\Rest;

Rest::resource('shows', ShowsController::class)->middleware('auth:sanctum');

4. Ask.

POST /api/shows/search
{
  "search": {
    "filters": [{"field": "seats", "operator": ">=", "value": 500}],
    "sorts": [{"field": "starts_on"}],
    "includes": [{"relation": "stage"}],
    "gates": ["update"]
  }
}
{
  "current_page": 1,
  "data": [
    {
      "id": 2,
      "title": "Opening night",
      "status": "planned",
      "seats": 1200,
      "starts_on": "2026-07-03",
      "gates": {"authorized_to_update": {"allowed": true, "message": null}},
      "stage": {"id": 1, "name": "Main stage"}
    },
    {
      "id": 3,
      "title": "Late night jazz",
      "status": "sold_out",
      "seats": 650,
      "starts_on": "2026-07-04",
      "gates": {"authorized_to_update": {"allowed": true, "message": null}},
      "stage": {"id": 1, "name": "Main stage"}
    }
  ],
  "from": 1,
  "last_page": 1,
  "per_page": 50,
  "to": 2,
  "total": 2,
  "meta": {}
}

Each row says whether the user may update it, so the frontend knows which buttons to show.

In a hurry? php artisan rest:quick-start asks which models to expose, then writes their resources (fields and relations read from the tables), controllers, starter policies and routes.

One resource, every endpoint

Rest::resource('shows', ShowsController::class) registers:

Route Endpoint What it does
GET /api/shows details Describes the resource for the current user: fields, rules, relations, actions, metrics, abilities
POST /api/shows/search search Filters, sorts, includes, aggregates, text search, pagination
POST /api/shows/mutate mutate Creates and updates rows and their relations, in one transaction
POST /api/shows/actions/{action} operate Runs a custom action on the rows a search matches, on listed ids, or on none
POST /api/shows/metrics/{metric} metric Computes a value, trend, partition, progress or table
DELETE /api/shows destroy Deletes rows (soft deletes when the model uses them)
POST /api/shows/restore restore Restores soft deleted rows, with ->withSoftDeletes() on a model that uses SoftDeletes
DELETE /api/shows/force forceDestroy Deletes rows for good, with ->withSoftDeletes() on a model that uses SoftDeletes
GET /api/shows/actions/{action}/batches/{batch} batch Progress of a queued batch, with ->withBatchProgress()

only(), except(), names(), middleware() and middlewareFor() shape the routes like any Laravel route.

Search: ask for exactly what the screen needs

One body combines text search, scopes, nested filters, filters through relations, aggregates and the sorts on them, includes and selects.

{
  "search": {
    "text": {"value": "night"},
    "scopes": [{"name": "upcoming"}],
    "filters": [
      {"field": "seats", "operator": ">=", "value": 500},
      {"nested": [
        {"field": "stage.name", "value": "Main stage"},
        {"field": "artists.name", "operator": "like", "value": "The%", "type": "or"}
      ]}
    ],
    "aggregates": [{"relation": "artists", "type": "count"}],
    "sorts": [{"field": "artists_count", "direction": "desc"}],
    "selects": [{"field": "title"}],
    "includes": [{"relation": "artists", "selects": [{"field": "name"}]}]
  }
}
The response
{
  "current_page": 1,
  "data": [
    {
      "title": "Late night jazz",
      "artists_count": 3,
      "artists": [
        {"name": "Ada Moon", "pivot": {"role": "support"}},
        {"name": "Kofi Brass", "pivot": {"role": "headliner"}},
        {"name": "Nina Volt", "pivot": {"role": "guest"}}
      ],
      "@more": []
    },
    {
      "title": "Opening night",
      "artists_count": 2,
      "artists": [
        {"name": "The Lumens", "pivot": {"role": "support"}},
        {"name": "Nina Volt", "pivot": {"role": "headliner"}}
      ],
      "@more": []
    }
  ],
  "from": 1,
  "last_page": 1,
  "per_page": 50,
  "to": 2,
  "total": 2,
  "meta": {}
}

@more lists the includes that hold more rows than they returned.

This search uses two more declarations on the resource: Scope::make('upcoming') in scopes(), and Contains::make() in text() with ->searchable() on the title field.

  • Filters take the operators of their field type, and/or, nested groups, dotted paths through relations (stage.name) and relation groups ({"relation": "artists", "exists": false}).
  • Includes take their own filters, sorts, selects, aggregates, limit and includes, and an alias to load one relation twice.
  • Text search runs on LIKE (Contains), the full-text index of MySQL, MariaDB or PostgreSQL (FullText), or a Laravel Scout engine such as Meilisearch, Typesense or Algolia (ScoutEngine).
  • Instructions add your own query logic, with typed and validated fields.
  • Outside HTTP, Rest::search(ShowResource::class)->as($user)->payload($saved)->lazy() replays a saved search in a job or an export, with the same validation and policies.

Mutate: write a whole graph in one request

{
  "mutate": [
    {
      "operation": "create",
      "attributes": {"title": "Closing night", "seats": 800, "starts_on": "2026-07-05"},
      "relations": {
        "stage": {"operation": "attach", "key": 1},
        "artists": [
          {"operation": "attach", "key": 4, "pivot": {"role": "headliner"}},
          {"operation": "create", "attributes": {"name": "Echo Park"}}
        ]
      }
    }
  ]
}
{"operations": [{"operation": "create", "key": 4, "relations": {"stage": {"operation": "attach", "key": 1}, "artists": [{"operation": "attach", "key": 4}, {"operation": "create", "key": 5}]}}]}

Every entry is validated by the rules of its fields and checked against the policies before the first write, then everything runs in one transaction. An Enum field can offer only some of its cases to writes, ->offered([...]), so a withdrawn status stays readable and filterable on old rows. Relation entries also take attach and detach, plus sync and toggle on many-to-many relations and delete on child rows, and a relation can limit them with onlyOperations() and withoutOperations(). Add a response block to get the written rows back, and versioned() on the resource to answer 409 when a row changed since the client read it.

A write can ask first: when mutateConfirmation() on the resource (or destroyConfirmation(), restoreConfirmation(), forceDestroyConfirmation()) returns a Confirmation, the request answers 428 with a signed token and writes nothing, and the same body sent back with "confirmation": "<token>" runs it.

A mistake comes back on its exact key. Here, an entry without title, with "seats": -3 and a created_at:

{
  "message": "The mutate.0.attributes.title field is required. (and 2 more errors)",
  "errors": {
    "mutate.0.attributes.title": ["The mutate.0.attributes.title field is required."],
    "mutate.0.attributes.seats": ["The mutate.0.attributes.seats field must be at least 0."],
    "mutate.0.attributes": ["The created_at key of the mutate.0.attributes field is not writable on create."]
  }
}

Actions: your business operations, as endpoints

class CancelShows extends Action
{
    public function fields(): array
    {
        return [Text::make('reason')->rules('required')];
    }

    public function authorizeEach(): ?string
    {
        return 'update';
    }

    public function handle(ActionFields $fields, Collection $models): void
    {
        foreach ($models as $show) {
            $show->update(['status' => 'cancelled']);
        }
    }

    public function respond(ActionFields $fields, int $impacted): ?ActionResponse
    {
        return ActionResponse::message("{$impacted} shows cancelled: {$fields->reason}");
    }
}

Declare it in the resource's actions(), and it runs on the rows of a search, once the policy lets the user update each of them:

POST /api/shows/actions/cancel-shows
{
  "fields": [{"name": "reason", "value": "Storm warning"}],
  "search": {"filters": [{"field": "stage.name", "value": "Main stage"}]}
}
{"data": {"impacted": 2, "result": {"type": "message", "message": "2 shows cancelled: Storm warning"}}}

The search block is required: "search": {} runs the action on every row the user may reach. Each chunk of rows runs in its own transaction: ->atomic() puts the whole run in one, and ->transactionPerRow() hands each row to handleRow() in a transaction of its own. Implement ShouldQueue to process the rows in queued chunks, and BatchableAction to run them as a batch whose progress the client can follow; the exports recipe builds a CSV download that way. An action can also target listed ids or no row at all, and ask the user to confirm before it runs.

Metrics: dashboards without extra endpoints

class ShowsByStatus extends Partition
{
    public function calculate(Builder $query): PartitionResult
    {
        return $this->count($query, 'status');
    }
}
{"data": {"type": "partition", "parts": [{"key": "planned", "label": "planned", "value": 2}, {"key": "sold_out", "label": "sold_out", "value": 1}], "other": null}}

Value, Trend, Partition, Progress and Table cover counts, sums, averages, medians and percentiles, with date ranges, time zones, the previous period and a result cache. A metric computes over the rows the client is allowed to see, and accepts the filters of a search.

And everything around it

  • Authorization: your policies run viewAny on every resource a request reaches, before validation, and create, update, delete, restore or forceDelete on every row it writes, before the first write. perimeterQuery() scopes each resource to the rows a user may reach (a tenant, a team).
  • OpenAPI documentation: install Scramble and /docs/api documents every endpoint, with a typed body per resource, request examples and error responses.
  • Details for frontends: GET /api/shows?with=fields.filter,fields.rules,actions.authorized tells a frontend how each field filters, which rules each form field follows, and which actions the user may run.
  • Precognition: live form validation with Laravel Precognition on every endpoint, once rest.precognition.enabled is on.
  • Predictable limits: list sizes, nesting depths, totals, value lengths and the rows one search renders are bounded in config/rest.php, and an oversized request answers one clear 422 before any query. A partition or a trend keeps its largest groups, 100 by default, and folds the rest into other.
  • Translated messages: every message the package writes for a client ships in English and French and follows the locale of the request; php artisan vendor:publish --tag=rest-lang lets you reword them or add a language.
  • rest:check for CI: reports routes without authentication, models without a policy, resources that show every row (no perimeterQuery()), actions without row checks and relations that accept detach on a foreign key that does not accept null.
  • Generators: rest:resource --generate reads the table, and rest:controller, rest:policy, rest:action, rest:instruction, rest:metric and rest:response scaffold the rest.
  • Laravel Boost: the package ships a Boost skill with the full feature reference.

Contributing

Contributions are welcome. Read the contributing guide first.

License

Laravel Rest Api is open-source software licensed under the MIT license.