The Dentally NexGen API uses calendar‑versioned, header‑based revisions behind a fixed URL prefix. This lets us roll out non‑breaking and breaking changes side by side while letting clients opt in at their own pace.
The URL carries a fixed major: every operation lives under
/v2.The dated revision is selected per request via the
Dentally-API-Versionheader:GET /v2/patients Dentally-API-Version: 2026-07-01Each dated revision has its own self‑contained OpenAPI document. Once a dated revision ships, its contract is immutable.
Multiple revisions are reachable in parallel until a revision is sunset.
Each version moves through four phases:
| Phase | When | Behaviour |
|---|---|---|
| Opt‑in | released_at → default_from | Reachable only with an explicit Dentally-API-Version header. Existing clients are unaffected. |
| Default | default_from → deprecated_at | The version returned to clients that omit the header. |
| Deprecated | deprecated_at → sunset_at | Still reachable. Lifecycle headers and warnings flow on every response. |
| Sunset | >= sunset_at | Gateway returns 410 Gone. The backend never sees the request. |
Long‑term‑support (LTS) versions follow the same shape with an extended deprecated_at → sunset_at window.
Every response echoes the version that handled it:
| Header | When | Meaning |
|---|---|---|
Dentally-API-Version: <id> | always | The version actually used to serve the response. |
Warning: 299 - "Dentally-API-Version header missing; defaulted to <id>." | header omitted | You were routed to the current default. Pin a version. |
Deprecation: @<unix-ts> (RFC 9745) | resolved version is deprecated | Timestamp at which the version became deprecated. |
Sunset: <http-date> (RFC 8594) | resolved version is deprecated | Date the version will be removed. |
Link: <…/changelog/<id>>; rel="sunset" | resolved version is deprecated | Link to the per‑version changelog. |
Warning: 299 - "API version <id> is deprecated and will be removed on <sunset_at>." | resolved version is deprecated | Human‑readable warning. |
| You send | Server does |
|---|---|
| Valid header | Routes to that version. |
| No header | Routes to the current default and adds the Warning: 299 "missing" header. |
| Unknown version | Returns 400 Bad Request (Problem Details) with a Link to this page. |
| Sunsetted version | Returns 410 Gone (Problem Details) with a Link rel="sunset" to the changelog. |
- Pin the version your client was built against. Don't rely on the rolling default.
- Watch the
Sunsetheader in your monitoring and pre‑emptively migrate before it lands. - Stay on LTS for long‑lived integrations to maximise the migration window.
For per‑version differences, see the Changelog.