The Getting Started section provides examples on how to use the MT1 server API.
The MT1 server API allows you to:
Generally, you can use the MT1 server API with any programming language which supports REST.
Realtime evens (e.g. device triggers) are propagated via a websocket (STOMP over SockJS protocol).
- Access realtime triggers of an MT1 device
- Access historical triggers of an MT1 device
- Make use of the server side trigger handling (full event management)
In order to use the API you will need a user account on the MT1 platform. If you do not have one already, you can register one here.
It is important that your user has enabled the Timekeeper feature. If you haven't enabled this feature during registration you can upgrade your account in the Account section.
In general, to use the API you would need to programmatically authorize first. Further explained in the following sub section.
Calling the authorization API will give you an authorization token, which will be needed to access other APIs, e.g. related to a device.
The authorization token will expire after some hours, however, there is no guarantee on the exact expiration time.
You can check whether the authorization token is still valid by calling the following REST API:
You will either receive a non-successful response, meaning that your token is invalid or expired, such as:
Or you will receive a successful response, meaning that the provided token is valid:
Alternatively, if an authorization token expires you will receive the HTTP status 403 Forbidden for any REST call which needs authorization.
As a consequence, it is recommended to authorize once, then re-use the authorization token for all API calls until the authorization token expires. After expiration of the authorization token you re-authorize using the same API as the initial authorization.
API Quota Limitation
In order to enforce the recommended and a fair usage of the API, described in the above paragraph, the MT1 server implements an API call quota.
The API quota is time-based and uses your client's IP address as user identification.
The quota limit is adapted quite frequently and therefore undocumened at the moment, however, too many login attempts within a short time period will exceed the quota limit very soon.
If you have exceeded the quota limit, the result of any REST call will give you the following result:
In order recover from this state you have to:
- Stop performing REST calls for some time (10 to 90 seconds).
- Adapt the general usage of the MT1 server, or
- request a change of the quota limit (email@example.com).