Headless Exponential #

This page is for application creators who want Exponential's content model, editing and permissions without its templates: a mobile app, a single-page application, a static site generator, another system that shows the content.

Contents #

1. What you keep and what you replace
2. Choosing the API
3. Reading content
4. Rich text, images and links
5. Preview and drafts
6. Caching and performance
7. Hybrid: templates and API together

What you keep and what you replace #

Choosing the API #

A front end that runs in the browser on another host calls the REST API only after CORS is switched on for its origin in rest.ini [CorsSettings]; it is off by default (CORS for the REST API). A browser or mobile app that signs users in is a public OAuth client and uses PKCE (PKCE and state).

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"

Public content can be served to anonymous API users only if rest.ini [Authentication] RequireAuthentication allows it; the default requires a user. For public front ends, use a read-only integration user and keep its key on your server.

Rich text, images and links #

• Each REST field has type, identifier, value, id and classattribute_id. A rich text field's value is plain text: its rendered output with the tags stripped.

• OutputFormat=xhtml adds renderedOutput: the whole node rendered by templates, in view mode rest, inside the template set in rest.ini [<controller>_viewContent_OutputSettings] Template (rest_pagelayout.tpl). The shipped rest_pagelayout.tpl is only a placeholder page; override it, and add a node/view/rest.tpl, in your design to get markup you can use.

• Images: an image field's REST value is only the path of the original file, relative to the site root (for example var/<site>/storage/images/.../name.jpg); it carries no aliases, no size and no alternative text. To get alias URLs today:

  • call the expservices image domain, ezjscore/call/expimage::url::<node id>::<attribute>::<alias> for one alias (the file is generated when missing) or expimage::urls::<node id>::<attribute> for every configured alias, each with url, absolute_url, width, height and MIME type (Remote services); or
  • write them into your rest view template ($node.data_map.<attribute>.content.<alias>.url) and read renderedOutput.

  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 and drafts #

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 this early; it is the part teams forget.

Caching and performance #

• The REST framework has an answer cache (rest.ini); the rest caches are cleared with the content tag.
• Cache in your front end or CDN; purge on publish with a workflow event or a listener that calls your purge hook (Workflows, triggers and events).
• Fetch lists in pages with limits.

Hybrid: templates and API together #

Many projects keep the site in templates and add an app on the API. That keeps preview, layouts and SEO simple for the site, and gives the app the same content. Start hybrid unless there is a reason not to.

Related pages #

• REST API v1 and v2 for applications
• OAuth and API keys
• APIs and protocols standard
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.