API Versioning
Target most up-to-date API base URL
The major versions of our APIs are distinguished by the version indicator in the URLs (currently V2). When a new major version becomes available, we will support the previous version for at least six more months, running the two APIs in parallel.
Minor version updates are reported on this page, but will not result in a new version indicator in the API URLs. All minor updates are considered to be “backwards compatible”. Only when changes are not “backwards compatible”, we will issue a new major version of the API.
What are minor changes?
We will consider an API change to be “minor” when it fits within our backwards compatibility specifications. Your server or client implementation developed against our APIs should be able to work with these changes happening over time:
- The addition of new API endpoints with new services (of course, you do not have to use these features instantaneously)
- The addition of new optional request parameters to existing API endpoints
- The addition of new fields to existing API responses, or to objects in existing API responses
- Reordering of fields in API responses
- Fields marked as required in the request can be made optional
- Increase or decrease of the size and internal format of identifiers (although these will not increase above the maximum specified length)
Note that you must make sure that your implementation will not break on any of these changes, as they can happen at any time without prior notification.
How will we inform you of upcoming major API updates?
We will actively contact you to inform you of upcoming new major API releases. The major releases will result in a new version-indicator in the API endpoint URLs.