Guide 06 · Developer docs

The APIs: REST, GraphQL and custom endpoints

Every Core dna site answers three kinds of API request under /cdna-api: REST for everything, GraphQL for reads that span several entity types, and web events for endpoints you define yourself as jobs. Which fits which task, one worked request for each, and what is true of all three. Jobs were called hooks until the module was renamed Orchestration; the API's routes still use the old name.

L1–L3
Unit 02 · Writing content

Versioned content and the live revision

Writing content Page 9 of 25 Updated

Most content does not change when you edit it: the edit becomes a new revision beside the old ones, and only the one marked live is what visitors see. Which records work this way, the three separate things that decide what is on the site, and how to read them.

Who this is for. The integrations engineer writing content, and anyone whose write “saved” without changing the site. The concept is explained for editors in Revisions, publishing and approval; this unit is about what the API does with it.

Which records are versioned

Pages; books, units and book pages; blog posts; FAQ pages and questions; custom entity records; product and category descriptions; forms; and files and images. Each keeps its content (its name and, for the types that have them, its layout areas) in revisions, and an edit to that content makes a new revision rather than changing the old one. Other records, such as products, categories, menus, users and site data, are not versioned: an edit to them applies at once and keeps no history.

Revisions, the live one and the newest one

  • revisions is the history, oldest first.
  • activeRevision is the live one: the content templates render and visitors see.
  • lastRevision is the newest. It is not always the live one: an edit that was saved but not made live, or a rollback, leaves them apart.

A revision has a type: version, the normal kind, or draft, which cannot be made live until it is saved as a version. An edit that changes nothing makes no revision.

Which revision is live, and which is newest 
GET /cdna-api/pages/page/1885?properties={id,activeRevision{id},lastRevision{id},navSection:activeRevision.areaText(navSection)} HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Response 200 OKSaved but not live 
{
  "result": "success",
  "data": {
    "id": 1885,
    "activeRevision": {
      "id": 3277
    },
    "lastRevision": {
      "id": 3424
    },
    "navSection": "API sandbox"
  }
}
Real response from this documentation site, on its API sandbox page

Here an edit made revision 3424, but the page still shows revision 3277. Comparing the two ids is the quickest test for “my edit saved but the site did not change”.

Three separate things decide what is on the site

DecidesSet with
The live revisionWhich content the record showsactiveRevision (Making a revision live)
PublishedWhether visitors can see the record at all, and from whenpublished, a datetime
Take-downWhen it stops being visibleunpublishAt

They do not move each other. Making a revision live does not publish an unpublished page; publishing does not choose a revision; scheduling a take-down changes neither. A write that should change what visitors see may need two of them.

Reading a versioned record

The record's own fields (id, slug, published, parent) are on the record. Its content is on the revision: activeRevision.name, and the layout areas through activeRevision.areaText(name). Reading layout areas has the selectors. The rest of this unit is about writing:

Go deeper
GuideRevisions and the active revision ReferenceEdit a page: API reference FAQMy edit saved, but the site did not change

Was this page helpful?

Your answer goes to the docs team.