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 · Headless, over the three API surfaces

What a headless build must rebuild

Headless, over the three API surfaces Page 7 of 29 Updated

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.

Who this is for. The lead estimating a headless build. This page turns an architectural preference into a number: each item below is work your front end takes on, with what it involves and which calls it rests on, so that you can size it against your framework. It gives no day counts, because they depend on the framework and on how many kinds of record have URLs.

Routing

Every incoming path has to become a record, or a 404. For pages, GET /cdna-api/pages/page/{path} does the lookup and resolves custom URLs on the way (REST). Every other kind of record with a URL, posts, products, book pages, custom entity records, has a route of its own, so your router decides which kind a path belongs to before asking. Keep the home page's id in your configuration and read it by id.

Rewrites and redirects are a second part of routing. Editors enter them in the admin, and the platform applies them only to the pages it renders itself, before anything else. Your router reads them and applies them in the same order:

The site's rewrites, in the order they apply 
GET /cdna-api/rewrites/rewrites?limit=3&orderBy=position&properties={id,source,target,matchType,action,redirectCode} HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Response 200 OK 
{
  "result": "success",
  "totalCount": 42,
  "data": [
    {"id": 15, "source": "/docs/global/user-documentation", "target": "/user-docs", "matchType": "exact", "action": "redirect", "redirectCode": 301},
    {"id": 16, "source": "/docs/global/user-documentation/content/common/categories-1", "target": "/user-docs/content/common/categories", "matchType": "exact", "action": "redirect", "redirectCode": 301},
    {"id": 17, "source": "/docs/global/user-documentation/content/common/configuration-2", "target": "/user-docs/content/common/configuration", "matchType": "exact", "action": "redirect", "redirectCode": 301}
  ]
}
Real response from this documentation site

matchType is exact or regex; action is redirect, sent with redirectCode, or rewrite, which serves the target's content at the source path. Cache the list in your front end and read it again when it changes.

Preview

A route in your front end that renders a draft revision, never cached, behind a URL nobody can guess, reached from the admin's live preview. The platform provides the entry point, the Alternative live preview url setting; the route is yours. Preview without a public URL describes it.

The sitemap

The platform's /sitemap.xml lists the platform's own URLs. Yours is built from the API: every published record with a URL, its path and its modified date, leaving out records whose robots setting is Don't index, but follow or Don't index and don't follow (the two the platform's generator leaves out), with language alternates taken from each page's related language versions.

Redirects and 404 handling

A path that matches no rewrite and no record is your 404 page, sent with a 404 status so that search engines drop it. Redirects come from the rewrites above. Old URLs from a previous site are usually added there in bulk at go-live, so the router must read them before the first visitor arrives.

SEO tags

Every record carries SEO settings: title, description, keywords, canonical URL, alternate URLs, robots and share image, read through the API as seoSettings{title,description,canonicalUrl,robots} and so on. The fallbacks are yours too: what to print when an editor left the title empty.

Caching and invalidation

API responses are not cached by the platform, so your front end caches them, and it needs to know when to drop them. A job on the record types you show, calling a revalidation endpoint of yours, does that (Knowing when content changed).

The worksheet

Fill in the last column against your framework before committing. The total is the real cost of going headless, and it is the part stakeholders do not see.

ItemWhat it involvesRests onEstimate
RoutingPath to record for each kind of record with a URL; the home pageThe page-by-path route; each module's routes
Rewrites and redirectsExact and regular-expression matches, redirect and rewrite actions, re-read on change/cdna-api/rewrites/rewrites
404 and error pagesStatus codes and templates for missing records and failuresA 404 from the API
Rendering layouts and componentsOne renderer per layout and per component layoutareasContent, or areaText(name) per area
PreviewA secret-protected, uncached route rendering a draft revisionThe Alternative live preview url setting; a backend credential
Drafts kept outretrieveUnpublished=0 on every public read, and a published check on reads by idThe published filter
SEO tagsPrinting each record's settings, with fallbacksseoSettings
SitemapAll published records with URLs, robots respected, language alternatesThe list routes
Cache and revalidationA cache in your front end, and an endpoint a job callsA job with entity events and an HTTP request action
FormsRendering each form, its validation messages and its steps/cdna-api/forms/submission/{id}
Member pagesSign-in, registration, password reset, the account areaThe visitor routes
Go deeper
GuideWhat a headless build gives up GuideDrafts, preview and knowing when content changed GuideRedirect mapping ReferenceRewrites

Was this page helpful?

Your answer goes to the docs team.