Versioning and stability
The Integration API is versioned on an additive-only principle: in this version of the API things are only added. An existing field is not removed and does not change its meaning. A change that breaks that does not go into the current version — it carries a new version of the API.
What fits in, what requires a new version
Section titled “What fits in, what requires a new version”| Change | Outcome |
|---|---|
| a new optional field in a response | fits in this version |
| a new value in a code list | fits in this version |
| a new address | fits in this version |
| removing an existing field | requires a new version of the API |
| changing the meaning of a field | requires a new version of the API |
| a new required field in a request | requires a new version of the API |
An API client that ignores a field it does not recognise is not broken by the first three rows — they only add. The last three change the existing shape and therefore require a new version, published separately.
The same rule applies to the codes in the code lists:
- An existing code never changes its meaning. A code that means one thing today does not start meaning something else in a later release.
- A withdrawn code is not reused for something else. Once a code goes out of use, it is left empty — it is not assigned to a new value.