Guide
Versioning
Which changes are backwards compatible, and when a new API version is required.
The API version is part of the path, for example /api/v1/. Every resource under the same version follows the rules on this page.
Backwards-compatible changes
- New resources may be added.
- Existing JSON objects may gain new fields.
- A resource may gain further optional parameters.
- Code lists may gain new values, for example a new status or error code.
Build your client so that unknown JSON fields are ignored and unknown code values can be handled without stopping the whole integration.
Changes that require a new version
- An existing field is removed or renamed.
- The data type or the established meaning of a field changes.
- The response takes on a different overall structure.
- Previously valid calls start being rejected because of stricter validation.
Changes driven by law or by a source
A data source, a change in law or a supervisory authority may require that a field stop being distributed. This applies particularly to personal data. Should that happen, we contact registered integration owners as soon as possible.
The current machine-readable definition lives at /api/v1/openapi.json. The file is generated by the same application that serves the calls, and is therefore the technical source of truth.