Headless Statamic in 6.31

Most Statamic sites render their pages with Antlers or Blade and never turn the API on. That is probably why REST API changes rarely get much attention. This release is worth a closer look if you run a separate frontend or connect Statamic to other services. McDade explained the idea a day later in a blog post called “Headless, Not Clueless”.

Handles you had to know

The REST API has delivered entries, terms, globals, nav trees and assets for years. What it could not do was tell you which collections, navs or asset containers a site has. A frontend that wanted the blog posts had to request /api/collections/blog/entries, so it needed to know that the collection is called blog. Navs and asset containers worked the same way, with the handle in the URL.

For a frontend written for one site, that is no problem. The developer knows the handles because they set them up. It gets harder for tools meant to work on any Statamic site, such as an addon, a search connector, or a content browser. Each of them needed a settings screen where someone typed in the handles by hand.

Single entries had a similar gap. The entry endpoint only accepted an ID. A frontend that receives a request for /about knows the slug, so it had to query the list endpoint with filter[slug]=about and take the first result.

The new endpoints

Two of the pull requests add endpoints that describe the site instead of its content. The listings for collections, taxonomies, navs and asset containers also include the API URL of each resource, so a tool can follow those links without building URLs itself.

Collections, taxonomies, navs and asset containers also have a single endpoint, for example /api/collections/blog.

None of this opens anything new by default. The listings respect the existing resources settings in config/statamic/api.php. If only the blog and pages collections are enabled there, /api/collections shows only those two. Sites are a new resource and start disabled, so /api/sites needs 'sites' => true first. Only the ping endpoint answers as soon as the API is on.

Requests that fit a frontend

The other three pull requests change how content is fetched. The blog post sums them up in one request:

GET /api/collections/pages/entries/about?site=fr&fields=id,title,content

The entry endpoint now accepts a slug as well as an ID. If a slug matches another entry’s ID, the ID wins. On a multisite collection, the site parameter decides which localization the slug refers to. Without it, Statamic uses the collection's first site.

The site parameter itself is also new. Entries, terms, and term entries accept ?site=fr, which is shorter than the existing filter[site]=fr. Leaving it out keeps the old behaviour and returns entries from all sites.

The fields parameter already worked on list endpoints. Single entries and assets ignored it and always returned every field. Now a frontend can request fields=id,title,slug for an index page and the full entry only when someone opens it.

The last fix is the least visible. Pagination links in the response kept filter, limit, page and sort, but dropped fields and query_scope. A sync job that followed the next link got page 2 with every field and without its query scope. Since 6.31 the links keep both, along with the new site parameter.

What the API still doesn’t tell you

The new endpoints name the containers, but not what is inside them. A tool learns that a collection called blog exists. It does not learn which fields its blueprint has or which field holds the teaser image. For that it still has to load an entry and look at the keys, or someone has to configure it. Statamic’s GraphQL API goes further. It builds a type for each blueprint, and introspection lists their fields. Since 6.3, though, introspection is only enabled locally by default.

The REST API also remains read-only. It delivers content, but a frontend cannot create or update entries through it.

And it remains a Pro feature. Statamic’s licensing page lists headless mode via REST API and GraphQL among the features exclusive to Pro, and every API route runs through middleware that requires Pro. Since May, a Pro license costs $349 per site.

What this means for your sites

If your sites render their own templates, nothing changes. The API stays off unless you enable it, and the new resources follow the same settings as the old ones.

If you already run a headless frontend, the slug lookup and the site parameter are the parts you will notice first. They replace filter queries that every project had to write for itself. Check your pagination as well: if a frontend or sync job relied on the next link, it now keeps the field list and query scope it started with.

The discovery endpoints matter most for people who build tools for other people’s sites. An addon or connector can now offer a list of real collections and navs in its settings instead of a text field for handles. Whether such tools appear depends on the community, and the missing blueprint information will limit how far they can go without configuration.