RESTful API conventions

The LYNKS API is a RESTful API, following market best practices for design and implementation.

HTTP Verbs

We're using HTTP Verbs in the following way:

HTTP Verb	Used for	Returns
`POST`	Creating a new resource or array of resources	`201 Created` ID(s) of the newly created resource(s)
`GET`	Getting a resource by ID Getting a list of resources by using filters	`200 OK` Full representation of the resource
`PUT`	Updating a resource	`200 OK` Full representation of the resource
`PUT`	Linking resources together	`204 No content`
`DELETE`	Deleting a resource	`204 No content`

Media types

The API uses application/json as content type for all endpoints that receive and return payload objects. The only exception if the GET /token endpoint to retrieve the access and refresh token. This endpoint uses application/x-www-form-urlencoded as defined by the OAuth2 specification.

HTTP return codes

Return code	Meaning
`200 OK`	Returned on `GET` methods if the call was successful. The response body contains the full representation of the resource.
`201 Created`	Returned on `POST` methods if the resources were successfully created. The response body contains an array of resource IDs of the resources that were created.
`204 No Content`	Returned on `DELETE` methods if the operation was successful. No body is returned.
`400 Bad Request`	Returned on any method if the request was badly formatted, either syntactically (e.g. wrong or missing parameters, bad formatting...) or semantically (e.g. the submitted resource objects are invalid).
`401 Unauthorized`	The API client has not used proper authentication to access the APIs. All APIs expect an `Authorization` HTTP header with a bearer token.
`403 Forbidden`	The technical user that has successfully authenticated does not have the necessary permissions to access the given API method.
`404 Not Found`	The resource that was requested does not exist or the authenticated technical user does not have permissions to access this instance of the resource.
`503 Unavailable`	The LYNKS API is temporarily not available.

Error object

All error responses (4xx or 5xx return codes) contain a response body with the detail of the error, following the RFC specification.

Property	Description
type	URI reference that identifies the problem type
title	Short summary of the problem type
status	HTTP status code of the problem
detail	Explanation specific to this occurrence of the problem
instance	A reference that identifies the specific occurrence of the problem
validationErrors	[POST/PUT requests only] Semantic or constraint validation errors of the provided resources

Example

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Language: en

{
 "type": "some-problem-type",
 "status": 400,
 "title": "Method arguments not valid.",
 "instance": "ec4138ea-673e-11ee-8c99-0242ac120002",
 "detail": "One or more accounts have failed validation.",
 "validationErrors": [
   {
     "errorMessage": "Account name cannot be longer than 35 characters",
     "inputIndex": 2
   },
   {
     "errorMessage": "IBAN is invalid",
     "inputIndex": 13
   }
 ]
}

Pagination

All Find resource API methods allow the result set to be retrieved in a paginated way. Pagination values are provided as query parameters.

Parameter name	Value
unpaged	No pagination. If set to true, the endpoint will return all results and pageIndex / pageSize will have no effect. Defaults to false.
pageIndex	The index of the page that the client wants to retrieve
pageSize	The size of the page (number of entries) the client wants to retrieve.

If a client intends to paginate through a result set, it is strongly recommended to use the same page size for all subsequent calls as for the first call to avoid unpredictable results.

The response of a paginated request will contain the header X-Total-Count informing of how many records that match the request exist. Example:

HTTP/1.1 200
Content-Type: application/json
X-Total-Count: 400

<other headers>

<response body>

Sorting

All Find resource API methods allow the result set to be sorted by a list of properties that are proprietary to the API method.

Parameter name	value
sort	Sorting criteria in the format: property,(asc\|desc)

Filtering

All Find resource API methods allow the result set to be filtered by a list of properties that are proprietary to the API method.