API Versioning
API versioning is a strategy used to manage changes in an API over time without disrupting existing partners. It allows introducing new features, improvements, and fixes while maintaining backward compatibility. This ensures that a partner using an older version of the API can continue to function without modification, even as the API evolves.
Scheme
The Partner API version consists of a MAJOR and MINOR part (e.g., 2.1).
- MAJOR: Introducing breaking changes.
- MINOR: Extending the API by introducing non-breaking or acceptable breaking changes (see below).
Introducing a new major version of the API
The process for introducing a new major version of the Partner Web API is as follows:
- When a breaking change needs to be introduced (see here for the definition of a breaking change), it is checked with all partners whether the change is acceptable and can be implemented.
If that is the case, the breaking change will be introduced in the current major API version by creating a new minor version.
Otherwise, a new major version of the API will be created.
note
Until the identification of a breaking change requiring a new major API version, the versioning concept described below will not be active.
- The users of the Partner Web API will be informed of a new major API version (including details of the breaking changes) on the release notes.
- The previous major API version will be deprecated and supported for 6 months following the release of the new major API version. (For details, see history).
The API versioning works differently for the REST API endpoints and the Webhooks. You will find the details here:
History
| Major API Version | Release date | Deprecated on |
|---|---|---|
| 1 | 2023-09-01 |
Breaking Changes
A breaking change is any modification to the API or the underlying services that requires existing clients to make changes to their code or configurations in order to continue using the API. Breaking changes can range from minor tweaks to major redesigns, but they all have the potential to disrupt existing workflows and cause compatibility issues.
What is a breaking change
- Removing an endpoint.
- Changing the structure of an endpoint.
- Changing or removing a mandatory header.
- Adding a mandatory header.
- Renaming or removing a field from the request body.
- Adding mandatory fields to the request body.
- Changing the type of a request field.
- Removing enum values on requests.
- Renaming or removing a field from a response body.
- Changing the type of a response field.
- Changing the format of the response.
- Adding a new validation rule to an existing parameter.
- Changing the authentication mechanism.
What is NOT a breaking change
- Adding new endpoints.
- Adding optional parameters to the request body.
- Adding an optional request header.
- Adding fields to the response body.
- Adding response headers.
- Adding enum values.