The Partner API is a RESTFull API with different endpoints which return JSON data regarding all sorts of resources.
Resources are accessed via standard HTTP requests in UTF-8 format to an endpoint. The Partner API uses the following HTTP verbs:
Method | Action |
---|---|
GET | Used for retrieving resources |
POST | Used for creating resources |
PUT | Used for changing or replacing resources |
DELETE | Used for removing resources |
OPTIONS | Can be issued against any resource to request CORS support |
The Partner API normally returns JSON in the response body (unless explicitly defined otherwise).
Below is a list of status code that are in use. Each resource endpoint will document all response codes that could be expected.
Status Code | Description | Methods |
---|---|---|
200 | OK - The request has succeeded. The client can read the result of the request in the body and the headers of the response. | all |
201 | Created - The request has been fulfilled and resulted in a new resource being created. | POST PUT |
202 | Accepted - The request has been accepted for processing, but the processing has not been completed. | POST PUT DELETE |
204 | No Content - Request is processed successfully but no response payload is returned. | PUT DELETE |
301 | Moved Permanently - This request and all future requests should be directed to the response's given URI. | all |
303 | See Other - Response has a Location header with a URL to which the client should redirect. | POST PUT DELETE |
400 | Bad Request - Error indicating that the server cannot process the request due to something that is perceived to be a client error (e.g. malformed request syntax, invalid request). | all |
401 | Unauthorized - Credentials are not valid for the target resource (client is denied server-authentication). | all |
403 | Forbidden - Request is successfully understood but client is not authorized to use or access this resource. | all |
404 | Not Found - Requested resource is not found. | all |
405 | Method Not Allowed - HTTP method is not allowed for the request's URI. | all |
409 | Conflict - Current state of target resource conflicts with the request. | PUT DELETE |
415 | Unsupported Media Type - Requested content-type is unknown to server. | all |
428 | Precondition Required - Client has not specified required precondition(s). | all |
429 | Too Many Requests - Client has exceeded rate limits and sent too many requests. | all |
500 | Server Error - Unexpected server execution resulting in a failure to respond successfully. | all |
503 | Service Unavailable - Server is currently unable to fulfill request. Client is suggested to try again later. | all |
504 | Gateway Timeout - Server did not receive a response to the request within a timely window. Client is suggested to verify expected results before trying again. | all |
The Partner API uses a single response to describe an error. This error response can be detected by the returned status
code (4XX
or 5XX
) and the Content-Type
header which will have a value of application/problem+json
.
The response itself will be a JSON structure according to RFC-7807. In general this response looks like:
{
"type": "about:blank",
"status": 403,
"title": "Forbidden",
"detail": "You don't have permission to access this resource."
}
status
property contains the status code from the response.title
property contains short a human-readable summary of the occurred problem.detail
property contains a detailed human-readable description of the occurred problem and usually provides more
insight into the resolution (if any).type
property describes the type of problem and can be used as a discriminator for problem variants with
additional properties. Type about:blank
is the default and will only contain the aforementioned properties.Example of a non-default problem type
{
"type": "/problems/violations",
"status": 400,
"title": "Bad request",
"detail": "The request contains one or more violations. Please resolve all of them and try again.",
"violations": [
{
"property_path": "/customer_id",
"in": "body",
"detail": "This value must be a valid UUID."
}
]
}
Note
If a resource endpoint supports one or more of the problem types they will be documented as a possible response.
If the response is for a collection of resources its structure will always look like the following.
{
"query": {
// applied query
},
"result": [
// 0 or more resources
{
"name": "Resource 1"
},
{
"name": "Resource 2"
}
],
"total": 2
}
query
property will always contain the query parameters that have been applied to get the resulting resources.
These include all provided query parameters and those not provided, but with a default.result
property will contain a list of zero or more resources matching the executed query.total
property will contain the total number of resources matching provided query parameters.If a resource supports the limit
and offset
query parameters the collection response will only contain a subset of
the total available resources (a single page).
limit
parameter can be used to control the maximum amount of resource returned per page.offset
parameter can be used to control the index of the first resource returned. E.g. ?offset=0&limit=25
gives the first page of 25 resources. ?offset=25&limit=25
gives you the second page of 25 resources.The response will always be a collection response in which the used (provided or default) values for limit
and offset
are available in its query
property. The total
property provides the total amount of resources
available in the system which gives you insight in the total number of "pages" that could be retrieved.
{
"query": {
"limit": 25,
"offset": 0
},
"result": [
// resources for first "page".
],
"total": 34
}
In the documentation of requests to the API and responses from it, you will frequently encounter properties with a
data format
.
For example
The id
property of a customer has string <uuid>
as its data type where uuid
is the format for the string
that
will be returned.
The list below provides some clarification on what these mean and how to handle them.
Format | Clarification | Example |
---|---|---|
integer<int32> |
4 byte signed integer between -2^31 and 2^31-1 |
7721071004 |
integer<int64> |
8 byte signed integer between -2^63 and 2^63-1 |
77210710045682438959 |
number<float> |
binary32 single precision decimal number - see IEEE 754-2008/ISO 60559:2011 |
3.1415927 |
number<double> |
binary64 double precision decimal number - see IEEE 754-2008/ISO 60559:2011 |
3.141592653589793 |
string<date> |
RFC 3339 internet profile - subset of ISO 8601 | "2023-05-11" |
string<date-time> |
RFC 3339 internet profile - subset of ISO 8601 | "2023-05-11T06:23:57Z" "2023-05-11T06:23:57+02:00" |
string<email> |
RFC 5322 | "example@example.com" |
string<uri> |
RFC 3986 | "https://example.com/" |
string<uri-reference> |
RFC 3986 | "/path/to/resource" |
string<uuid> |
A Universally Unique IDentifier. See RFC 4122 | "e1f2b196-40a2-48c0-892c-1e4c9502ec96" |
string<json-pointer> |
RFC 6901 | "/gross_price/amount" |
string<iso-3166-alpha-2> |
Two letter country code - see ISO 3166-1 alpha-2 | "NL" |
string<iso-4217> |
Three letter currency code - see ISO 4217 | "EUR" |
string<iso-13616> |
IBAN standard - see ISO 13616 | "NL02ABNA0123456789" |
string<iso-9362> |
Business Identifier Codes (BIC), a unique identifier for business institutions - see ISO 9362 | "AABNNL2AXXX" |
string<iso-639-1> |
Two letter language code - see ISO 639-1 | "en" |
string<bcp47> |
Multi letter language tag - see BCP 47. It is a compatible extension of ISO 639-1 optionally with additional information form language usages, like region, variant and script. |
"en-US" |
string<ulid> |
A 128-bit sortable unique identifier. "Universally unique Lexicographically sortable IDentifier" | "01BX5ZZKBKACTAV9WEVGEMMVS1" |