Guide 01 · Developer docs

Choosing how to build

Decide where the pages of a Core dna site are composed before writing code: on the platform, in your own application, or on the platform with a few pieces filled in by the browser. The decision tree, each shape in depth, multi-brand and languages, and a table and case studies to make the call.

L2

Unit 02 of 06 6 pages

Headless, over the three API surfaces

Updated 23/10/2026 01:43

What a headless front end works with and what it takes on: the three API surfaces, the credentials, what is given up and must be rebuilt, drafts and cache invalidation from outside, and when headless is the right call. For teams weighing headless, and those already building it.

Start with the three surfaces, because the choice between them decides how many requests a page costs: REST for complete records and every write, GraphQL for one shaped read, a synchronous job for an endpoint of your own. The authentication page then says which credential each kind of client uses, and why a browser on another origin cannot call the API at all.

The next two pages are the honest part. What a headless build gives up is the list for the stakeholder who decides; what it must rebuild is the same list as work to estimate. The drafts page covers the first thing every headless build settles, that a backend credential reads unpublished records too, along with preview and cache invalidation. The unit ends with the cases where headless is right and the three arguments for it that are not.

In this unit

Read in order

01 REST, GraphQL or a custom endpoint The three ways a headless front end reaches the platform, each with a real request: REST for complete records and every write, GraphQL for one shaped read across record types, a synchronous job for an endpoint of your own. Then how to choose, by round trips and caching. 02 Authenticating an external application Which credential a headless front end's server, a staff app or a script should use, how a token and a key are told apart, why a browser on another origin gets nowhere, and why a site member's sign-in is not an API credential. 03 What a headless build gives up The list to take to whoever is deciding: what a server-rendered Core dna site has without anyone writing it, and what a headless front end loses, keeps, or can partly win back. 04 What a headless build must rebuild Routing, preview, the sitemap, redirects and 404s, SEO tags and cache invalidation: what each involves on Core dna, the API calls it rests on, and a worksheet that turns a preference for headless into an estimate. 05 Drafts, preview and knowing when content changed Why a headless front end shows drafts to the public unless every request says otherwise, how editors preview your front end without a public URL, and how a job tells your front end that content changed, scheduled publishing included. 06 When headless is right, and three wrong reasons The cases where headless is a requirement, and the three reasons that come up at every kickoff and are not: a team that knows a JavaScript framework, the word in a brief, and a speed problem the page cache already solves.