API change handling
About
In order to use the collectAI platform, our REST API and optionally webhooks have to be integrated. In general, we try to keep the API and its data contracts as stable as possible. We aim for non breaking changes and try to evolve the API with easy adoption in mind. However, from time to time, breaking changes may be required to provide you new features or improved API usability. This document gives you more insights how this is managed in order to provide you a transparent and smooth experience on this topic.
A breaking change is a change within the API which causes an application consuming it to fail.
Principles
-
If possible, breaking changes are avoided.
-
Breaking changes are communicated upfront with a sunset date.
-
Breaking API changes can be switched on individually and tested on the demo environment.
-
Breaking changes will be applied on production once the sunset date is reached.
Change process
A regular tech newsletter informs about all API changes (breaking and non-breaking changes). The newsletter includes a link to all relevant information.
In case of breaking changes, an additional email will be sent out, informing you about the need for action and the corresponding sunset date. The email contains typically a link with more detailed information about the change.
In case you are unable to make the required changes before the communicated sunset date, please consult your account manager.
Announced breaking changes can be individually enabled for you in our demo/production environment. Please consult your account manager for this. We are highly recommending to test your integration with our demo environment, ideally with a test system of yours.
Every update will be communicated in our Changelog and Tech blog sections: