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 06 of 07 3 pages

Client code and imports

Updated 23/10/2026 01:51

How to structure the code that talks to the API: the scripts on a server-rendered or hybrid site, and the server-side imports and syncs that move records in and out. For the JavaScript developer and the integrations engineer.

The unit teaches an architecture rather than snippets. The first page is for the JavaScript developer: one module owns the base URL, the CSRF token and every request, each kind of failure gets its own answer, a cart updates at once and then defers to the server, drafts survive a reload, and data the page already rendered is never fetched again.

The next two pages are for the integrations engineer and run on a server. The external-id pattern comes first because everything else depends on it: it is what makes an import safe to run twice, and every guide that imports data links to it. Then the page on bulk reads and failures sizes and paces a long run and says what to do when it stops halfway. Settle the credential first, in Credentials and access; how a write changes versioned content is in Writing content.

In this unit

Read in order

01 Writing the client layer An architecture for the scripts on a server-rendered or hybrid site, not snippets: one module owns every request, each kind of failure gets its own answer, an optimistic cart defers to the server, drafts are saved without secrets, and data the page already has is never fetched twice. 02 The external-id pattern Store the other system's identifier on every record you import, and look it up before every write, so that running an import twice leaves the site exactly as running it once did. Where externalId exists, the upsert, what to handle yourself, the test, and duplicates in the source. 03 Bulk reads and failure handling Settings that let a sync or an export read a whole catalogue without slowing a production site, an incremental read that pages by id, and what to do when a run fails halfway: which requests to retry, which to read before resending, and what to log.

Objects ReferenceGenerated from the platform, so it is always current

API ReferenceEvery REST endpoint, in cURL, PHP, Python and JavaScript

Client code and imports

In this unit