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.

Incompatible changes

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.

Versioning

When we release a new version, previous versions will be phased out and sunset over a reasonably long time.


Whatโ€™s Next