Concepts

Api Calls

The Partner API is a RESTFull API with different endpoints which return JSON data regarding all sorts of resources.

Base URL

The base address of the Partner API is https://partner-api-001.prd.jifeline.cloud.

Requests

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

Responses

The Partner API normally returns JSON in the response body (unless explicitly defined otherwise).

Response status codes

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

Error response

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."
}
  • The status property contains the status code from the response.
  • The title property contains short a human-readable summary of the occurred problem.
  • The detail property contains a detailed human-readable description of the occurred problem and usually provides more insight into the resolution (if any).
  • The 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.


Collection 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
}
  • The 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.
  • The result property will contain a list of zero or more resources matching the executed query.
  • The total property will contain the total number of resources matching provided query parameters.

Pagination

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).

  • The limit parameter can be used to control the maximum amount of resource returned per page.
  • The 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
}

Data types

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"