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

patchRevision, revisions, or a revision by id

Writing content Page 10 of 25 Updated

Three request shapes write the content of a versioned record, and they differ in what they keep. patchRevision copies a revision and changes only what you send; revisions without an id replaces everything; revisions with an id rewrites a revision in place. Which to use, with the two keys that make a patch safe.

Who this is for. The integrations engineer changing content that people also edit in the admin. Use patchRevision unless you have a reason not to.

You sendThe platformUse it to
patchRevisionCopies a revision, applies only the keys you send, saves the copy as a new revisionChange one layout area, one component or the name, and keep everything else. The normal case
revisions, no idMakes a new revision holding only the name and layout areas you send. Every layout area you leave out is empty in itWrite a whole record from a source system that owns all of its content
revisions with an idRewrites that revision in place: no new revision, no history, even if it is the live oneCorrect a revision without leaving a trace. Rarely what you want

All three save a revision that is not live unless the request also says "activeRevision": true, inside the patchRevision or revisions object. At the top level of the body, activeRevision takes a revision id instead, and true there is refused with a 422 “expecting an id”.

A patch that changes one layout area and goes live

Two keys make a patch safe. originRevision names the revision to copy, normally the live one; activeRevision: true makes the result live.

Change one layout area of the live revision and make it live 
PUT /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
Content-Type: application/json

{
  "patchRevision": {
    "originRevision": 3277,
    "activeRevision": true,
    "areaContent(navSection)": "API sandbox, patched"
  }
}
Response 200 OK 
{
  "result": "success",
  "data": {
    "id": 1885,
    "activeRevision": {
      "id": 3425
    },
    "lastRevision": {
      "id": 3425
    },
    "navSection": "API sandbox, patched"
  },
  "message": "The Page has been saved successfully."
}
Real response from this documentation site, on its API sandbox page

Inside patchRevision, besides those two keys:

  • name changes the revision's name, which is the record's title.
  • areaContent(name) replaces one layout area; Writing areas gives the value for each input type.
  • The collection keys change one element of a component collection: Editing component collections.
  • layout moves the copy to another layout. Areas the new layout does not have are dropped.

Why originRevision matters

Read activeRevision{id} before every patch and send it as originRevision, every time: without it, a patch copies the newest revision, not the live one, which only matters after a rollback or an edit that was saved but not made live. Rolling back has a worked example.

A full replace

revisions without an id is for a source that owns the whole record. Send every layout area, or lose the ones you leave out:

HTTP 
PUT /cdna-api/pages/page/1885
{
  "revisions": {
    "name": "API sandbox",
    "layout": 30,
    "activeRevision": true,
    "areas": {
      "navSection": "API sandbox",
      "pageSections": [
        { "name": "Section A", "layout": 40, "areas": { "body": "<p>Section A</p>" } }
      ]
    }
  }
}

Send areas as the layout area names, with values in the write shape for each: include every layout area you want the new revision to keep, since any left out, such as pageSections, are empty in it. A rollback to an older revision brings a left-out layout area back, because the old revisions still hold it.

Editing a revision by id

Put the revision's id inside revisions and the platform edits that revision instead of making one. There is no new revision and no history of the change, and if the revision is live, the site changes at once with no way back. Keep it for repairing a revision you have just created; for anything an editor might want to undo, patch instead.

The same on every versioned type

Pages, book pages, blog posts, FAQ pages and questions, product descriptions and custom entity records all take these keys on their edit route, with "activeRevision": true inside the object to go live in the same request. Keep every layout area write inside the revision object (patchRevision or revisions), on every type: that is where an edit route reads layout area changes, including on custom entity records.

Go deeper
ReferenceEdit a page: API reference ReferenceSeveral operations in one request: API reference How-toChange one area of a page without touching the rest FAQUpdating one area emptied the others

Was this page helpful?

Your answer goes to the docs team.