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 URLs and rely on 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 pretty much 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 cannot 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 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 cannot cater for any contrary assumptions you make its usage. For instance, a string field containing what looks like a GUID to you might end up containing something other than a GUID in the future. Thus, it is quite important to treat this field as an opaque string (as stated in the contract) and try not to read into its actual content.

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

When working with hypermedia controls, do not try to build the URIs yourself by introspection into 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 a different order to what you expected in the responses.