API Properties

Our APIs are provided as a REST service. New resources are added without notice. Deprecations are published as a news article and listed on the deprecations page 6 months before the resources are removed. The rest of this page explains the general workings and behaviour of our APIs. The list of available APIs and their documentation can be found here.

• Environments
• Contexts
• HTTP Methods
• Headers
  • Accept
  • Content-Type
  • User-Agent
• HTTP Response codes
• Rate limiting
• Versioning

Environments

We have three different environments.

Contexts

In the past, Ons API was offered in different contexts resulting in different base paths. Only the technical context, with base path /t/ is being used now. For backwards compatability, all endpoints must still be prepended with the /t/ base path (except for the /ping endpoint). Thus, the /clients/{id} endpoint on development will look like api-development.ons.io/t/clients/3.

HTTP Methods

Our APIs support the REST verbs as expected.

GET

Used to retrieve resources and related data. Query parameters are used to select a sub-set or apply some sort of filtering. Query parameters are almost always optional. Requests do not change server state. Common urls include:

POST

Used to create new resources or perform some kind of action. POST requests are also used when sensitive data is transferred (like a login). For a 200 return status the same resource is returned with some updated fields. Requests change server state.

PUT

Used to update an existing resource. The behaviour for POST also applies to PUT.

DELETE

Removes a particular resource or removes a relation between resources.

Headers

It is possible to add headers to HTTP requests to our API. There are three headers that are of interest.

Accept

This header is required and defines the returned format. For most cases requesting json or xml will be enough. Some APIs return octet-streams (bytes) and the /ping returns text/plain. If you request something that can’t be given, you’ll receive a 406 status code. You can enter multiple formats. The first one indicates your preference. Weights should also be supported.

Accept: application/json,application/xml

Content-Type

Required for POST and PUT calls. This header indicates the format used in the http body. You can only have one. The charset is optional but recommended.

Content-Type: application/xml;charset=utf-8

User-Agent

The User-Agent header is optional but it would help us to identify your requests when something goes wrong.

User-Agent: connector/1.1+http://your-domain.com

Where connector should be replaced with the name of your connector.

HTTP Response codes

Below you can find a table with http response codes you can expect.

Rate limiting

Currently we limit requests per connector to the following:

• 4 requests in parallel per certificate
• 100 requests per second (currently not enforced)
• 10.000 seconds of request time per day (currently not enforced)

The latest is measured as a sum for all requests being done. This can be 100.000 requests that take 100 milliseconds each or 1 request that takes 10.000 seconds. If you go over the limit, you’ll receive a 429 status code. Only the connection limit is currently enforced. In the future, we might enforce the other limits as well. However, we will first investigate whether or not connectors will be affected by this. Note that these limits are not meant to hold back any functionality of a connector. They are meant to prevent connectors from using inefficient APIs for their use-cases; using the correct APIs should not bring API usage close to the enforced limits.

Versioning

Our APIs are not versioned. Rather, we rely on marking resources as deprecated 6 months prior to removal. Keep an eye on the deprecation article and be prepared to adjust your connector. New resources are added as they become available, without further notice.