Matas API Documentation
How to use the API
API requests must include be made to the Matas API base url. https://api.matas.nl/api
Each request must include an Accept header with the value application/json.
Valid API request
As state above, the Matas API is located at https://api.matas.nl/api:
curl --header "Accept: application/json" "https://api.matas.nl/api/orders"
Expose the HTTP response headers
If you want to expose HTTP response headers, use the --include option:
curl --include --header "Accept: application/json" "https://api.matas.nl/api/orders"
Authentication
All API requests of the Matas API require authentication.
To authenticate yourself with the Matas API, you'll have to create a valid personal access token from the Matas Extranet. When making requests, the token must be included in the Authorization header as a Bearer token.
curl --header "Accept: application/json" --header "Authorization: Bearer :personal_access_token:" "https://api.matas.nl/api/orders"
If authentication information is not valid or is missing, the Matas API returns an error message with a status code of 401:
{ "message":"Unauthenticated." }
Status codes
The API is designed to return different status codes according to context and action. This way, if a request results in an error, you can get insight into what went wrong.
The following table gives an overview of how the API functions generally behave.
| Request type | Description |
|---|---|
| GET | Access one or more resources and return the result as JSON. |
| POST | Return 201 Created if the resource is successfully created and return the newly created resource as JSON. |
| PUT | Return 200 OK if the resource is modified successfully. The (modified) result is returned as JSON. |
| DELETE | Returns 204 No Content if the resource was deleted successfully. |
The following table shows the possible return codes for API requests.
| Return values | Description |
|---|---|
| 200 OK | The GET, PUT or DELETE request was successful, and the resource(s) itself is returned as JSON. |
| 204 No Content | The server has successfully fulfilled the request, and there is no additional content to send in the response payload body. |
| 201 Created | The POST request was successful, and the resource is returned as JSON. |
| 401 Unauthorized | The user isn’t authenticated. A valid personal access token is necessary. |
| 403 Forbidden | The request isn’t allowed. For example, the user isn’t allowed to delete a project. |
| 404 Not Found | A resource couldn’t be accessed. For example, an ID for a resource couldn’t be found. |
| 405 Method Not Allowed | The request isn’t supported. |
| 422 Unprocessable Entity | The entity couldn’t be processed. For example, a required parameter for a new resource was omitted. |
| 500 Server Error | While handling the request, something went wrong on the server. |
Pagination
The Matas API supports offset-based pagination. Almost all endpoints that return multiple results will be paginated.
Offset-based pagination
Sometimes, the returned result spans many pages. When listing resources, you can pass the following parameters:
| Parameter | Description |
|---|---|
page
|
Page number (default: 1).
|
per_page
|
Number of items to list per page (default: 15, max: 100).
|
In the following example, we list page 2 of all orders, while listing 30 orders per page
curl --header "Accept: application/json" --header "Authorization: Bearer :personal_access_token:" "https://api.matas.nl/api/orders?page=2&per_page=30"