Versioning and deprecation

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.

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.

Changes that are not breaking#

These can appear in the current version at any time, without notice. Build your integration so it keeps working when they do:

• 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 breaking#

These never happen silently. They ship in a new version, or, during the beta, follow the beta rule:

• 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.

Support window#

When a new version (for example /v2) is released:

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.

During the beta#

While the API is in beta, Wandura may still need to make a breaking change inside /v1. When that happens:

• 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.

Where to 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.