API Versioning

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: increased for incompatible API changes
  • MINOR version: increased for new functionality which is backwards-compatible
  • PATCH version: increased for backwards-compatible bug fixes

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:

  • e.g. Version 1: api.example.org/v1/asset/statuses
  • e.g. Version 2: api.example.org/v2/asset/statuses

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

Compatible changes, which do not break existing clients are:

  • add endpoints
  • add optional request headers
  • make required request headers optional
  • add optional request url parameters
  • make required request url parameters optional
  • add optional request body attributes
  • add response body attributes
  • any changes of the response body of 400 responses containing a error description

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

Incompatible changes, which can break existing clients are:

  • change response status codes
  • change response content type
  • remove or rename endpoints
  • add, remove or rename required request headers
  • remove or rename optional request headers
  • change data types of request headers
  • make optional request headers required
  • add, remove or rename required request url parameters
  • remove or rename optional request url parameters
  • change data types of request url parameters
  • make optional url parameters required
  • remove or rename optional request body attributes
  • add, remove or rename required request body attributes
  • make optional request body attributes required
  • remove* or rename response body attributes

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.

Usage Metrics

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:

  1. Count of API calls
  2. Used database storage
  3. Used file storage

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.

Counting Metrics

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.