As the business cases we support evolve over time, so does our API.
To keep it up to date, we are constantly modifying it in a backwards compatible manner. To do so, we first ensure that the existing functionality is 100% supported and that we do not cause any disruptions to our existing integrated partners.

Non-breaking changes

Non-breaking changes are often deployed to our API by adding new endpoints, or new fields to existing endpoints. This way the current integrated partners can just make use of this new functionality just by extending their integration with us.

🚧

Body parsing

Based on the above, you need to make sure that your body parsing technique is flexible and allows for new unknown fields to be parsed, essentially being able to ignore them until you extend the integration. The rest of the fields will always be sent and no field is removed within the same API version.

Breaking changes

When we need to introduce breaking changes, we do so by introducing a new version and the urls are changed to reflect it. This means that the existing implementations will not be broken.

Legacy version support

When we introduce a new API version, we support the previous version for at least one year from the day the new version is released. This way we give plenty of time to our partners to update their integration with us. Once every partner has integrated to the new version, the old version will be decommissioned and start responding with HTTP 505.