Headless with the DXP
This page is for developers and architects who use the DXP as a content back end for other clients: a single-page
application, a mobile app, a static site generator, a kiosk. Editors keep working in /adminui/; your clients read
(and sometimes write) through the APIs.
Contents
- Which API for which client
- The content model is your API
- Authentication per client
- Images
- Caching
- Previews and links
- First-release checklist
Which API for which client
| Client needs | Choose | Why |
|---|---|---|
| Exactly the fields of a screen, few round trips | GraphQL | One query, the fields you ask for |
| Create and update content, upload files | REST | Full create, update and delete on the repository |
| A server-rendered site | Twig in the DXP itself | No API at all |
Both can be used side by side.
The content model is your API
Content type identifiers and field identifiers become GraphQL types and fields, and appear in REST responses. Agree them with client developers before editors fill content, version changes like an API, and regenerate the GraphQL schema in the same change (GraphQL).
Authentication per client
- Public, read-only content: anonymous requests, limited by the Anonymous role.
- Apps and services: one user per client, a role with only the policies it needs, JWT tokens (JWT authentication).
- Browsers on another origin: allow exactly their origins with
CORS_ALLOW_ORIGIN(The REST API, CORS).
Images
Clients should request variations, never originals. Define variations for the sizes your clients show (Image variations); include the width and height in what you send.
Caching
Anonymous GET requests go through the HTTP cache, which the DXP purges when content changes
(HTTP cache and Varnish). Authenticated requests are personal; cache them in the client,
not in a shared proxy.
Previews and links
A decoupled front end needs its own routes for content. Decide early how a location maps to a client URL (for example
by the URL alias the API returns) and how editors preview drafts; the DXP's preview in /adminui/ renders with the
site's Twig templates, not with your client.
First-release checklist
- To do: The API prefix is read from configuration in every client (Where it lives).
- To do: Every client has its own user and a minimal role.
- To do: JWT keys are generated on every environment and backed up.
- To do: CORS lists only your origins.
- To do: The GraphQL schema is committed and matches the content types.
- To do: Image variations exist for every size a client shows.
- To do: Anonymous responses are cached and purged on publish.
Related pages
- Headless with the REST API (for organizations)
- The REST API
- GraphQL and GraphiQL
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.