API versioning and deprecation
What the v1 in CMS Orbit's addresses promises, which changes can arrive without notice, how breaking changes are announced and how long you have, and how the SDKs are versioned.
Reference5 min read
Websites and scripts built on CMS Orbit should keep working without you watching them. This page says what we promise for each API, what can change without notice, and how we tell you before anything changes that needs work on your side.
Our policy: This page is CMS Orbit's versioning and deprecation policy, and the notice periods and support windows on it apply today. If the policy changes, the change is announced in the changelog, and it never shortens a notice already given.
What is versioned
/cms/v1/…v1/cms/manage/v1/…v1/cms/graphqlx-orbit-signature headerv1 is the first and only version of each REST API. There is no v2 yet.
What v1 promises
Within v1, a request that works today keeps working, and keeps answering in a shape your code can read. We do not, without notice:
- remove an endpoint, a parameter or a field from an answer
- rename any of them, or change a field's type
- make an optional parameter or body field required
- change what a status or an error
codemeans, or move a case to another status - change the GraphQL schema other than by adding to it
- rename a webhook event or change how it is signed
The endpoints under Endpoints for the CMS screens in the Management API are not covered. They follow CMS Orbit's own screens and may change with them.
Changes that need no notice
These can arrive at any time, so build your code to accept them:
- New endpoints, parameters, fields and GraphQL types. Ignore fields you do not know, and do not fail on them.
- New values in fields that list kinds or states, such as a new block type,
kindorstatus. Have a sensible default for values you do not know. - New webhook events. Most events reach only webhooks that subscribed to them, but some reach every webhook, such as
delivery.pausedanddelivery.resumed, and new ones may too. Answer2xxto events you ignore. - New error codes for new cases, and new keys in
details. Fall back on the HTTP status for codes you do not know. - Error and validation messages. They are for people, can be reworded, and in the management API follow
Accept-Language. Never match on them. - The order of keys in JSON, and of items where the docs do not give an order.
- Limits that grow, such as rate limits or page sizes.
- Lengths and formats of ids, tokens and keys, beyond their prefix (
cms_pk_,cms_sk_,cms_mt_,whsec_).
The Field types and the generated types from npx cms-orbit generate show what your content holds today. Run the generator again after changing content types.
Breaking changes
A breaking change is any change on the list in What v1 promises, or any change that makes a working website, app or script need changes on your side.
- Announced in the changelog, marked Breaking change, with an action box that says exactly what to do and by when. You can filter the changelog to breaking changes only, or follow it by RSS, where these entries start with "Breaking:".
- At least 90 days' notice before the old behaviour stops, for the delivery API, GraphQL, the documented management API endpoints and webhooks. During that time both work, wherever both can.
- A new version for big changes: when a change is too large to make side by side, it comes as a new version, such as
/cms/v2/, andv1keeps working for at least 12 months afterv2is released.
Answers do not yet carry Deprecation or Sunset headers. Watch the changelog.
When we may act sooner
We may change something with less notice, or none, when keeping it would put customers or their visitors at risk: a security problem, a way to read another organisation's data, or a behaviour that breaks the law. We then say so in the changelog the same day, with what to do.
A bug fix is not a breaking change when the old behaviour contradicted these docs. If many websites rely on the old behaviour, we treat the fix as a breaking change anyway.
SDKs
The SDKs follow semantic versioning: major.minor.patch.
@bifrost-orbit-cms/sdk on npmbifrost-orbit/cms-sdk on PackagistCMSOrbit with Swift Package Managercom.bifrostorbit:cms-sdk on Maven Central- While a version starts with 0, a minor release (
0.12.0to0.13.0) may include breaking changes. Each one is a line starting with Breaking: in the SDK's changelog, saying what to do. Patch releases (0.12.0to0.12.1) never break anything. Pin the minor version, such as~0.12.0on npm, and read the changelog before moving to the next. - From 1.0, breaking changes come only in a new major version.
- Old SDK versions keep working. An API change that would break an SDK version still in use counts as a breaking change of the API, with the notice above. Updating the SDK is never the only way to keep a website running.
- JavaScript SDK releases also appear in the changelog, as SDK entries. The PHP, Swift and Kotlin SDKs keep their changelogs with their packages.
Plan for change
- Ignore what you do not know: fields, values, events and codes.
- Check
statusanderror.code, never messages. See Error codes. - Pin SDK versions and update on purpose.
- Keep the address you call,
/cms/v1or/cms/manage/v1, in one setting, so moving to a new version is one change. - Follow the changelog's RSS feed, or filter it to breaking changes.
Was this page helpful?