Introduction to our APIs

Our APIs are built upon the REST architectural style. They accept JSON-encoded requests and return JSON-encoded responses.

The APIs provide predictable and stable resource-oriented URIs and rely upon widely known and established HTTP defaults and features like methods, response codes and headers. This makes it easy for you to implement your integration with any HTTP client library within your tech stack.

Connecting to the APIs

All requests towards our APIs are made using HTTP/1.1 and made secure with minimum TLS 1.2. Older HTTP clients running on obsolete frameworks or operating systems might receive connection errors. This is usually due to the client supporting only TLS 1.0 or SSL. These versions are all insecure and deprecated and can not be used. If you receive such errors, please ensure that you are connecting over TLS 1.2 by reading your library/framework's appropriate documentation.

Robust integrations

We recommend you to keep Postel's law (Robustness Principle) in mind when developing your integration towards our APIs.

"Be conservative in what you send, be liberal in what you accept"

While our APIs employ versioning, we also strive to design for extension. We will always uphold the contracts of our APIs as they are stated, but we can not cater for any out-of-bands assumptions you might have made by interpreting those. For instance, a string field containing what looks like a GUID to you might end up containing something else than a GUID in the future, thus you must treat this field as an opaque string (like stated in the contract) and not try to read into its actual content.

Likewise, your integration must be able to ignore fields that it does not understand, as we might very well add new fields and properties to the contracts in the future. Please do not confine yourself to the limits of our current documentation examples.

When working with hypermedia controls, please do not try to build the URIs yourself by introspecting their current content, as these URIs can change at any time.

We accept arbitrary ordering of properties in the requests we receive and ask that you also accept that properties might be returned in an order different from what you expected in the responses.