To ensure that API changes don't break existing clients, the API is versioned. The version number of the API is defined as MAJOR.MINOR.PATCH:
Major version changes can break existing clients, minor and patch versions do not.
New major versions always lead to new endpoint url's, containing the major version:
Old major versions are kept until all clients are migrated to a newer version or the support has ended, defined by our Terms & Conditions.
Compatible changes, which do not break existing clients are:
Structure changes of the request/response body are compatible if they only extend the existing scheme and don't break the rules for attributes.
Incompatible changes, which can break existing clients are:
Structure changes of the request/response body are incompatible, if the structure gets a new hierarchy, parts get deleted, required attributes are introduced, attributes are renamed or optional attributes get required.
(*) Removing response body attributes will not always break a client, but could lead to unwanted behaviour.
The usage for external entities is charged. Multiple payment plans are possible and depend on the business model. To enable a fair pricing model we will measure the API usage by three metrics:
Every call to the API sends the API key. The API key can be used to identify the clients application and therefore we can identify who to charge for usage.
1.Api calls: We count every call to the API. Every call is counted equally. We make no difference regarding the http method, endpoint or size of the request. Only exception to this are calls that cause a http 500 internal server error, which are not counted. For analysis we store this count in a database table.
2.File storage: File storage is counted per user and/or API key and may be limited according to the selected plan. Counted are either created or modified files. If an attachment is modified by multiple client applications, the files size is counted for all of them. The size being used for calculation is always the latest file.
Metrics may also be used to limit access to the API when predefined amounts of calls or storage is reached.