API change policy
Backwards compatible changes
We regard some changes of the API as backwards compatible, these changes can, but need not to be, communicated to the end users:
- adding new endpoints
- adding optional parameters for endpoints
- adding new fields to the responses
- removing of possible values (e.g. the value of a status which might never ever be returned)
- any and all changes to undocumented endpoints
Communication of backwards compatible changes
The documentation of backwards compatible changes might happen after the release. Undocumented endpoints, parameters and return values might have incompatible changes any time without communication.
We consider all other changes as incompatible, e.g.:
- removal of endpoints
- removal of parameters for endpoints
- removal of fields in responses
- change of default values
- adding new possible status
- changing the semantics of parameters/responses
Communication of incompatible changes
Incompatible changes will be documented and communicated upfront in time to give the users the time to change their client code.
Most likely, however, we will create a new version of the API to introduce incompatible changes.
When we release a new version, previous versions will be phased out and sunset over a reasonably long time.
Updated almost 6 years ago