Headless and decoupled front ends #

This page is for developers who want Exponential's content model, editing and permissions behind a front end built with another framework: a JavaScript application, a static site generator, a mobile app, or a site written in Laravel, Django or Rails. Exponential is not headless-only: it has its own templates, so you choose how much of the front end to replace (Headless Exponential).

Contents #

1. What you keep and what you replace
2. Reading content
3. Rich text, images and links
4. Preview
5. Caching and purging
6. Hybrid first

What you keep and what you replace #

Reading content #

curl -s -H "Authorization: Bearer $EXP_API_KEY" \
     "https://example.com/api/ezp/v2/content/node/<node id>/list/offset/0/limit/20?ResponseGroups=Metadata,Fields"

The REST API requires a user by default (rest.ini [Authentication] RequireAuthentication). For a public front end, use a read-only integration user with a role limited to what the site shows, and keep its key on your server, never in browser code (REST and JSON APIs).

Rich text, images and links #

• OutputFormat=xhtml returns rendered XHTML of rich text fields, so the front end does not parse the internal XML.
• Image fields carry the original and the aliases; define aliases for your front end's sizes in image.ini (Images and image variations).
• Links inside rich text point to site addresses; map them to your front end's routes by URL alias or node ID.

Preview #

Editors preview in the administration with the site's templates. A headless front end needs its own preview: read the draft version through an authenticated, editor-level call and render it in a protected preview route. Plan it early.

Caching and purging #

• The REST framework has an answer cache configured in rest.ini.
• Cache in your front end or CDN; purge on publish with a workflow event or a content/cache listener that calls your front end's purge or revalidation hook (Events and listeners).
• Fetch lists in pages with limits.

Hybrid first #

Many projects keep the public site in Exponential's templates and add an app or a JavaScript widget on the API. That keeps preview, layouts, SEO and URL aliases simple and gives the app the same content. Go fully headless when the front end really must live elsewhere. If the goal is a Symfony front end with Twig on the same content, look at the legacy bridge instead of the REST API (Mixing Exponential and a framework).

Related pages #

• Headless Exponential
• OAuth and API keys
• REST API v1 and v2
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.