Skip to content

A REST API for a Laravel CMS ​

Sooner or later a site needs to be read by something other than a browser: a mobile app, a front end in Next or Nuxt, a script that sends the week's numbers to a spreadsheet, a partner's system that books appointments. In a Laravel project that usually means a controller per model, a resource class per controller, some filtering written by hand, and a page of documentation that is out of date by the next release. Each new kind of record repeats it, and each one filters, pages and fails a little differently.

A site that came from WordPress has /wp-json/wp/v2/, and kitloom keeps it for the clients that speak WordPress. But its shape is WordPress's: per_page and X-WP-Total, title.rendered, one way of filtering for posts and another for terms. kitloom/rest-api is the API a new client should be written against: /api/v1/, named and shaped the Laravel way, one set of rules for every kind of record.

One way to ask, for every resource ​

Posts, pages, every post type and taxonomy of your theme, the media library, the authors, and the records of the modules you install — the bookings of a salon, for one — are all resources, and all answer the same query:

GET /api/v1/posts?filter[categories]=3,5&filter[published_at][gte]=2026-01-01
                 &sort=-published_at
                 &include=author,featured_image
                 &fields[posts]=title,url,published_at
                 &page[size]=10

filter, sort, include, fields and page are the same everywhere, and a list always answers data, links and meta. A name the resource does not have is a 400 that lists the names it does have — a typo in a filter never returns the whole table.

What makes this hold is that a resource declares its fields with a type: text, integer, date, one of a list, the ids of related records. The type decides which filters a field takes, whether it sorts, how a write is validated, how the value is written into the JSON, and what the OpenAPI document says about it. Nothing is described twice, so nothing drifts.

The Reference writes itself ​

In the admin, API → Reference lists every resource you may read: its addresses, its fields with their types, what can be written, how each is filtered and sorted, and what can be included. It is drawn for the person looking at it — an editor sees less than an administrator — and it changes the moment a module or a post type is added.

A program reads the same as an OpenAPI 3.1 document, /api/v1/openapi.json, also drawn for whoever asks. A developer generates a typed client from it instead of reading.

Tokens that act as a person ​

Without a token, the API reads what a visitor of the site sees: published posts, public pages, the services a salon offers. To read drafts, private records or the bookings, or to write anything, a client sends a token made under API → Tokens. It is an application password, the same as the WordPress REST API takes, so one set of tokens serves both.

A token is its owner: it sees what they see in the admin and may do what they may do. One made Read only never writes, whatever happens to it. Each shows when it was last used, and Revoke ends it at once.

Writes go through the same rules as the admin ​

The API never saves a model itself. A new post goes through the same writer as the admin's form: a contributor who tries to publish, or an author who edits someone else's post, gets a 403, a slug is made unique, the post's terms are assigned. A booking made through the API asks the salon's free times and waits for the salon's answer, as one made on the site does; a client moves only their own, and only until the salon's cancelling limit.

Two things a client cannot do by accident:

  • Overwrite a newer change. Every record answers a version. A client that sends it back with If-Match gets a 412 when someone saved in between, and nothing is written.
  • Delete for good without asking. A write that cannot be undone answers 428 with a question and a token for that one request; the client shows the question and sends the request again with the token.

While the site is closed for maintenance or "coming soon", the API reads nothing out to the people the holding page holds; the roles that see a closed site read on.

For a module's author ​

A module puts its records into the API by declaring a resource: its name, its typed fields, the query of everything a caller may ever see, who may do what, and a writer that hands on to the module's own. Filtering, sorting, paging, includes, versions, confirmations, the Reference and the OpenAPI document come with it. php artisan rest-api:check says whether every resource is sound.

Watch it ​

API: the Reference, a list read in the browser, and a read-only token
API settings: records on a page and requests a minute

Try it ​

Open a sandbox in one click, with no sign-up: Filament or Nova, and its /api/v1/ answers at once. Every query, field and status code is in the API guide.

Last updated:

kitloom — sites on Laravel, built for you and run with AI.
Contact · Services · License · Refunds · Privacy · Community · YouTube · [email protected]