API Properties
Our APIs are provided as a REST service. New resources are added without notice. Resources are deprecated 6 months before removal, and the technical contact registered in Ons API Dashboard is notified of the deprecation 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
We have three different environments, with their own URL.
environment | use | URL |
---|---|---|
DEVELOPMENT | Developing your connector using fictional data | https://api-development.ons.io |
STAGING | Test your connector on a customer’s test environment | https://api-staging.ons.io |
PRODUCTION | Run your connector on a customer’s production environment | https://api.ons.io |
Path and contexts
All endpoints start with the base path /t/
, except the /ping
endpoint.
Example
The path for the/clients/{id}
endpoint on development is: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:
Format | Use |
---|---|
/resource |
request all entries |
/resource/42 |
request a particular entry |
/resource/42/sub_resource |
request all entries related to an entry |
/resource/x-stream-connect/data |
request all entries in a streaming matter |
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.
Format | Use |
---|---|
/resource |
create a new resource |
/resource/42/sub_resource |
create a new sub-resource for resource |
/resource/42/action |
perform action for resource |
PUT
Used to update an existing resource. The behaviour for POST also applies to PUT.
Format | Use |
---|---|
/resource/42 |
update resource |
DELETE
Removes a particular resource or removes a relation between resources.
Format | Use |
---|---|
/resource/42 |
delete resource |
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. 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; in that case the first one indicates your preference. Weights should also be supported.
Applications which don’t specify the content-type in their accept-header wil receive JSON.
Accept: application/json
From mid 2024 only JSON is supported and not XML, not even if this is explicitly requested.
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/json
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.
Status | Text | Description |
---|---|---|
200 | OK | GET: valid response with your requested data in the response body. POST/PUT: valid response with your given resource enriched with some extra data in the response body. |
201 | Created | POST: object created, response has no body. There’s a Location header with the path where you can find the resource. |
202 | Accepted | PUT: changes are accepted, no response body. |
204 | No Content | POST: used for actions which were successful. GET: resource requested had no content. |
304 | Not Modified | GET: requested resource has not changed since it was last requested. |
400 | Bad request | GET: the combination of query params is invalid. POST/PUT: the given content is incorrect. You’ll receive an ErrorResponse body indicating what was wrong. |
401 | Unauthorized | You have insufficient rights to access the resource. |
402 | Payment required | Reserved for future use. |
403 | Forbidden | Authentication unsuccessful. |
404 | Not found | The requested resource was not found. |
406 | Not acceptable | Wrong Accept header. |
409 | Conflict | POST: The given resource already exists or was changed by another call. |
410 | Gone | The requested resource is no longer available at the requested address. |
423 | Locked | GET: The given resource is not yet ready. This is the case for delayed jobs that take some time to process. |
429 | Too many requests | You are being rate limited. |
495 | Invalid certificate | The SSL certificate is invalid. It might have expired, or it has not been signed by the correct certificate authority. |
500 | Internal server error | Something blew up on our side. We most likely got an error report, but it doesn’t hurt to report it. |
502 | Bad gateway | invalid upstream, this happens during updates. |
503 | Service unavailable | A service is down, this happens during updates. |
504 | Gateway timeout | A timeout somewhere in our infrastructure. This could happen due to updates or when our network is congested. It can also happen when your network is congested or broken. |
Rate limiting
Requests are being rate limited 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.
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)
Note
- 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.
- 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.
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.