Change history
Every change to this page, newest first. Expand an entry to see what changed.
← Versioning and API evolution
- 2 Oct 2026 · +67 −32 lines
Show changes
- # Versioning and deprecation + # Versioning and API evolution - > **TL;DR** — The version is in the path (`/v1`). Additive changes ship without notice. Breaking changes ship in a new version, and the previous version keeps working for **12 months** after the new one is announced. While the API is in beta, a breaking change inside `/v1` is announced at least **30 days** ahead, except urgent security fixes. + > **TL;DR** — The major version is in the path (`/v1`). Inside it, Wandura only **adds**; any change of shape ships as a new **dated version**, and your key stays pinned to the one it was created with. Read responses tolerantly (ignore unknown fields, unknown values = default case, unknown error codes = by status class) and your integration keeps working without code changes. Breaking changes get **12 months** of overlap, or **30 days'** notice during the beta. Dated versions, ready-made links, `GET /config` and deprecation headers are all live. ## How versions work {#how-versions-work} - The API version is part of every path: `https://www.wandura.ai/api/delivery/v1/…`. You choose the major version by the path you call; you do not have to set any header. Every response from `/v1` also carries `Wandura-API-Status: beta` while the API is in beta. + | Layer | Example | How you choose | + |---|---|---| + | Major version | `/api/delivery/v1/…` | The path you call. | + | Dated version | `2026-10-02` | Your key is pinned to the version current when it was created. Override per request with the `Wandura-Version` header. | - **Dated versions inside `/v1`.** The shape of responses inside `/v1` also carries a date (for example `2026-10-02`): your API key is pinned to the version current when it was created, every response says which one it used in the `Wandura-Version` header, and you can try a newer one per request by sending that header. A shape change then ships as a new dated version, and your key keeps the old shape until that version's sunset date. See [API evolution](api-evolution.md#dated-versions). + Every response says which dated version produced it in the `Wandura-Version` header, and carries `Wandura-API-Status: beta` while the API is in beta. - ## Changes that are not breaking {#additive} + ## Read responses tolerantly {#tolerant-reader} - These can appear in the current version at any time, without notice. Build your integration so it keeps working when they do: + | You | In return, Wandura | + |---|---| + | **Ignore fields you do not recognise.** Never validate responses against a closed schema. | Never removes, renames or retypes a field inside a dated version. | + | **Treat an unknown value as the generic case** (for `protection`, `status`…). | Announces new values in the changelog before returning them. | + | **Handle an unknown `error_code` by its status class**: `429` wait `Retry-After`; other `4xx` do not retry; `5xx` retry with backoff. | Never changes the code or status of a case that already has one. | - - A new endpoint. - - A new optional request parameter. - - A new field in a response. Ignore fields you do not recognise. - - A new error code, or a new value in a field that lists states. Always keep a default branch. - - A higher rate limit. + ## Changes that are not breaking {#additive} - The rules your integration should follow to stay unaffected are on [API evolution](api-evolution.md#tolerant-reader). + They can appear at any time, without notice: a new endpoint; a new optional parameter; a new response field; a new error code or enum value; a higher rate limit. ## Changes that are breaking {#breaking} - These never happen silently. They ship in a new version, or, during the beta, follow the [beta rule](#beta): + Never silent: removing or renaming an endpoint, parameter or field; a new required parameter; changing a field's type or meaning; changing authentication or the scope an endpoint needs; a different error code for an existing case; a lower rate limit. They ship as a new dated version, or a new major version, or during the beta under the [beta rule](#beta). - - Removing or renaming an endpoint, a request parameter or a response field. - - Adding a required request parameter. - - Changing the type or meaning of an existing field. - - Changing authentication, or the scopes an endpoint needs. - - Returning a different error code for a case that already had one. - - Lowering a rate limit. + ## Dated versions {#dated-versions} - ## Support window {#support-window} + - **Your key is pinned.** It receives the shape it was built against until that version's sunset date. Keys created before dated versions existed use `2026-10-02`. + - **Try a newer version per request** with `Wandura-Version: <date>`. When your code handles it, move your keys over: a **new** key is pinned to the latest version; **rotating** a key keeps its pin. + - **An unknown or retired version** in the header (or as your key's pin) answers `400` `unsupported_version`, with `supported_versions`, `latest_version` and, for a retired pin, `upgrade_to`. This check happens before the key check, and uses the flat format on every endpoint. + - How to move from one version to the next: [Migrating versions](../guides/migrating-versions.md). - When a new version (for example `/v2`) is released: + ### Version history {#version-history} - 1. Wandura announces it in the changelog and by email to the Admin of every organisation that uses the API. - 2. The previous version keeps working, unchanged, for **12 months** from that announcement. - 3. During those 12 months the documentation of the previous version stays available, marked as an older version, under its own address (for example `/v1/developers/…`). Use the version menu at the top of the API pages. - 4. After the 12 months the previous version is retired. Calls to it return an error that names the version to move to. + #### 2026-10-02 {#version-2026-10-02} - ## During the beta {#beta} + The first dated version: the `v1` shapes as of 2 October 2026. Supported; no sunset date. - While the API is in beta, Wandura may still need to make a breaking change inside `/v1`. When that happens: + ## Follow links instead of building URLs {#links} - - It is announced at least **30 days** before it takes effect, in the changelog and by email to the Admin of every organisation that uses the API. - - An urgent security fix may take effect immediately. It is announced as soon as it is live. + Responses carry the URLs you need next, absolute, in `links`: + | Endpoint | Links | + |---|---| + | [List licensed catalog](../reference/catalog.md) | `self`, `next` (`null` on the last page or when not paging), `playback`, `config` | + | [List creatives](../reference/creatives-list.md) | `self`, `next`; and `self` on each creative | + | [List open videos](../reference/videos-list.md) | `self`, `next` | + | [Get configuration](../reference/config.md) | every endpoint, the docs, the changelog feed | + + Cursors are opaque: copy them, never decode or build them. + + ## Read your configuration {#config} + + [`GET /api/delivery/v1/config`](../reference/config.md) tells your backend, for your key: the limits that apply to you, your playback settings and ticket lifetimes, batch limits, subtitle languages, the API versions (pinned, latest, supported) and every announced deprecation. Read it at start-up or every few hours instead of hard-coding these values. + + ## Deprecations and sunset dates {#deprecations} + + When an endpoint or a dated version is going away, Wandura announces it in four places at once: + + 1. **Response headers**, on every response served by it: `Deprecation: @<unix seconds>` ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)), `Sunset: <HTTP date>` ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)), and `Link: <https://docs.wandura.ai/…>; rel="deprecation"`. + 2. The `deprecations` list in `GET /config`. + 3. The machine-readable feed `https://docs.wandura.ai/changes.json` (`api_versions`, `deprecations`). + 4. The changelog, and an email to the Admin of every organisation that uses the API. + + A single deprecated field gets no header; it is listed in the other three places. Log these headers in your monitoring ([Observability](../production/observability.md)). There are no deprecations today. + + ## Support window {#support-window} + + When a new major version (for example `/v2`) is released, Wandura announces it in the changelog and by email to your Admins, keeps the previous version working unchanged for **12 months**, keeps its docs online as an older version, and then retires it: calls return an error naming the version to move to. + + ## During the beta {#beta} + + A breaking change inside `/v1` is announced at least **30 days** before it takes effect, in the changelog and by email to your Admins. An urgent security fix may take effect at once; it is announced as soon as it is live. + ## Where to follow changes {#follow-changes} - - **Changelog** — link at the bottom of every page. It lists every page that changed, by day. - - **Change history** — every page shows when it was last updated and links to its own history with the exact lines added and removed. - - **Feedback** — use **Send feedback** at the top of any page if something is unclear or a change caught you by surprise. + - **Changelog**: in the menu; every page changed, by day. + - **Change history**: each page links to its own history. + - **`changes.json`**: for your monitoring. + - **Send feedback** at the top of any page if a change surprised you. + + ## Related {#related} + + - [Migrating versions](../guides/migrating-versions.md) + - [Canonical API behaviour · Versioning](../reference/behaviour.md#versioning)
- 2 Oct 2026 · +1 −1 lines
Show changes
⋯ The API version is part of every path: `https://www.wandura.ai/api/delivery/v1/…`. You choose the major version by the path you call; you do not have to set any header. Every response from `/v1` also carries `Wandura-API-Status: beta` while the API is in beta. - **Rolling out — dated versions inside `/v1`.** The shape of responses inside `/v1` will also carry a date (for example `2026-10-02`): your API key is pinned to the version current when it was created, every response says which one it used in the `Wandura-Version` header, and you can try a newer one per request by sending that header. A shape change then ships as a new dated version, and your key keeps the old shape until that version's sunset date. See [API evolution](api-evolution.md#dated-versions). + **Dated versions inside `/v1`.** The shape of responses inside `/v1` also carries a date (for example `2026-10-02`): your API key is pinned to the version current when it was created, every response says which one it used in the `Wandura-Version` header, and you can try a newer one per request by sending that header. A shape change then ships as a new dated version, and your key keeps the old shape until that version's sunset date. See [API evolution](api-evolution.md#dated-versions). ## Changes that are not breaking {#additive} ⋯
- 2 Oct 2026 · +5 −1 lines
Show changes
⋯ ## How versions work {#how-versions-work} - The API version is part of every path: `https://www.wandura.ai/api/delivery/v1/…`. You choose the version by the path you call; there is no header to set. Every response from `/v1` also carries `Wandura-API-Status: beta` while the API is in beta. + The API version is part of every path: `https://www.wandura.ai/api/delivery/v1/…`. You choose the major version by the path you call; you do not have to set any header. Every response from `/v1` also carries `Wandura-API-Status: beta` while the API is in beta. + **Rolling out — dated versions inside `/v1`.** The shape of responses inside `/v1` will also carry a date (for example `2026-10-02`): your API key is pinned to the version current when it was created, every response says which one it used in the `Wandura-Version` header, and you can try a newer one per request by sending that header. A shape change then ships as a new dated version, and your key keeps the old shape until that version's sunset date. See [API evolution](api-evolution.md#dated-versions). + ## Changes that are not breaking {#additive} ⋯ - A higher rate limit. + The rules your integration should follow to stay unaffected are on [API evolution](api-evolution.md#tolerant-reader). + ## Changes that are breaking {#breaking} ⋯
- 2 Oct 2026 · Page created