For more information on available calls and messages structure goto the open api docs
Authentication and authorization is achieved using JSON web tokens. A token can be be obtained in 3 ways:
By default when a user is created a password request will be sent to the user via email. Once a password has been set a user can use that password to authenticate against the api.
POST /account/auth
{
"username": "string",
"password": "string"
}
When a pin has been set a user can use the pin in place of their password. The same api call can be used as per above.
POST /account/auth
{
"username": "string",
"password": "string"
}
For integrations an api key can be created which will allow you to limit access for that integration to only the relevant integration api’s. A token can be obtained using an API key as follows:
GET /account/auth?apiKeyId=string
Api keys are generated from the organisation module via the web application. Organisation administrator rights are required in order to do this. If you do not have administrator rights you will need to ask your organisation administrator to do this on your behalf. An api key is assigned permissions in a similar fashion to a user. Modules, roles and sites are allocated to the api key to allow access to the necessary areas. Generally there will be a specific Integration role which will provide access to the specific integration apis, however it is possible to allocate additional permissions to an api key which will give it the same access level as a normal user.
Once a valid token has been obtained it must be attached to each subsequent request with the HTTP authorization header in the following format:
Authorization: Bearer [token]
Note: The token must be prefixed by “Bearer “
Tokens expire after a predefined amount of time and will need to be refereshed using your password, pin or api key. For integrations it is recommended that a new token is obtained for each session or unit of work which is performed.
It is possible for certain actions to cause a token to be invalidated. When this happens the API will return an updated token in the Authorization header of the response. This updated token should be used for any subsequent requests being performed agains the api.
All API access is over HTTPS, and accessed from https://rest.trackmatic.co.za/api/v2. All data is sent and received as JSON.
All responses are wrapped in an envelope which contains metadata about the data being returned.
When collections of items are returned they will usually be returned as a paginated list. Pagination metadata is contained in the pagination section of the envelope as shown below. The data element of the response will contain the data which corresponds to the current page.
{
"pagination": {
"page_size": 0,
"page_no": 0,
"total": 0
},
"data": [
...
]
}
When returning data for a single resource it takes the following form:
{
"data": { ... },
"links": [{
"href": "https://...",
"rel": "..."
}, ...]
...
}
HTTP methods are used as per the below table.
| Method | Usage | Idempotent | Notes |
|---|---|---|---|
| POST | Create | Create a new resource | |
| PUT | Update | X | Update an entire resource |
| PATCH | Update | X | Update a partial resource |
| DELETE | Delete | Delete an existing resource | |
| GET | Read | X | Retrieve data |
Errors are returned using an appropriate HTTP error code. Some common error codes returned are as follows:
When returning an error code it is accompanied by an explanation of the error in the response body. The repsonse content takes the following form:
[{
"message": "string",
"type": "string", (optional)
"code": "string", (optional)
"key": "string" (optional)
}]
Note - The response is always an array of error messages
All date-time values MUST be provided as ISO 8601 UTC date-times and all responses are in the same format.
Time spans (Durations) are represents in the ASP.NET style time spans
1.23:59:59.999 [days.hours:minutes:seconds:milliseconds]
Shorter representations can be used when days and milliseconds are not applicable as follows:
23:59:59 [hours:minutes:seconds]
GPS coordinates are represented by an array of float values where the first item is the longitude and the second value is the latitude [longitude, latitude]. Each item in the array is in the decimal degrees (DD) format. See GEOJson RFC for further details.