Headless CMS publishing: define which records become public routes

Last updated: 5 Oct 20266 min read

tutorial

A headless publishing contract has at least four identities: CMS record ID, editorial status, public slug, and content revision. The frontend must define whether it reads content at build time, request time, or through a refresh job. A draft or private record should not enter the public route manifest. A published record should have a stable canonical path, validated fields, and a clear policy for slug changes and unpublishing. Pagination is part of correctness; fetching the first page of an API response can silently omit later records. Editorial timestamps alone are not sufficient when updates arrive out of order or a record is deleted.

Operational decision

Suppose the CMS contains 47 published lessons, 6 drafts, and 2 private notes. A publishing job requests all pages of the published collection, verifies that 47 distinct IDs were received, and builds routes from validated slugs. It records the CMS revision used by the build. A new lesson saved as a draft must remain invisible on the public site, even if its slug is known. Publishing it creates a route only after the next successful refresh or deployment; unpublishing removes that route or returns a deliberate gone response under the site's policy. A slug rename needs a redirect plan and a collision check before the old path disappears. Compare route inventory with the CMS inventory after each release.

CMS snapshot contract
Published IDs received: 47
Draft records excluded: 6
Private records excluded: 2
Route key: validated public slug
Revision: content snapshot identifier
Failure: incomplete pagination blocks promotion
Unpublish: route removed or explicit gone response

Cost and verification

Collecting P paginated records is O(P) in data transferred, with one or more network round trips per page. A build-time snapshot gives stable pages but introduces a delay until the next build; request-time reads reduce that delay but shift CMS availability into the reader path. Record the freshness target and choose the architecture against it. Measure missing routes, duplicate slugs, CMS-to-public revision lag, and unpublish lag rather than counting only successful API requests.

Common Mistakes

Do not assume that a saved CMS record is published.
Do not fetch only the first page of a paginated collection.
Do not let draft or private content leak through a public preview query.

Connected lessons

Practice and check

devops

web-publishing