API usage
Authentication
Client credentials to access the REST-API can be created by navigating to Settings -> ClientApiUser. When created, a client-id and client-secret will be automatically generated which can be used to access the api using the oAuth2 client-credential flow.
This client-id and client-secret can be used to request an authentication token at the authentication server.
Refer to the Swagger API documentation on your platform to get the token URL and API url.
Example token request:
POST /token HTTP/1.1
Host: authorization-server.com
grant_type=client_credentials
&client_id=api-cast4all-test
&client_secret=5zwnAnxIkkSD1WSpSjFa7AiaYs9rwRoZ
&scope=email profileExample response:
{
"access_token": "my-bearer-authentication-token",
"expires_in": 300,
"refresh_expires_in": 0,
"token_type": "Bearer",
"not-before-policy": 0,
"scope": "email profile"
}The access-token from the response can be used directly in every request to the REST-API.
Authorization: Bearer my-bearer-authentication-tokenReference fields
Each object/instance of an endpoint will be identified by a unique identifier. This identifier will be named as externalId, or endpoint +id (e.g. installationId) within the API responses. Linked objects will contain an externalId that can be used to retrieve more information.
Below, some examples show the installation response with a link to the installationType and communicator endpoints.
{
"identification": "string",
"externalId": "string",
....
....
"installationType": {
"resourceUri": "string",
"name": "string",
"externalId": "string"
},
"communicator": {
"resourceUri": "string",
"externalId": "string"
}
}Filtering
The API supports following filtering parameters, only the ones available in the swagger documentation can be used.
| Description | Example |
|---|---|
| equals: value should match parameter value exactly | installation=123456 |
| lower than: value should be lower than parameter value | fromTimestart=2020-07-30T22:00:00Z |
| greater than: value should be higher than parameter value | toTimestart=2020-07-30T22:00:00Z |
Sorting
The API supports sorting on each GET endpoints which returns a list of elements. Sorting information can be passed to the application with the sortby query parameter. Below some examples:
| Value | Description |
|---|---|
| - | default sorting will be applied |
| identification | sorting on identification will be applied ascending |
| identification:asc | sorting on identification will be applied ascending |
| identification:desc | sorting on identification will be applied descending |
| identification,dateFrom:desc | sorting on identification ascending and dateFrom descending will be applied respectively |