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.