Getting started

Introduction

The Getting Started section provides examples on how to use the MT1 server API.
The MT1 server API allows you to:

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)

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).

Prerequisite

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.

General Usage

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.

Info Please note that you should use at least TLS 1.2. Older versions of TLS/SSL can not be guaranteed to be supported.

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 (office@alge-timing.com).

Parallel API calls

In order to provide a REST API with fast response times for all users of the platform, the MT1 server implements a transaction limit for parallel REST calls.
The following limits are currently in place:

Parallel transactions (REST calls) are handled sequentially by the server to ensure consistency.
If a transaction is blocked by one ore more preceeding transactions for more than ten seconds, the transaction is cancelled by the server.

In such a case, the server will respond with the following response: A single transaction, in the context of the MT1 server, is defined as a single REST call, which changes the state of a sports event. Examples for such transactions are:

Cancelling a run
Editing run times
Resetting a run

In order to avoid this limitation, you should ensure that you perform only one transaction at a time and wait for the response before performing the next transaction. For most purposes, the MT1 server provides APIs which allow to perform multiple actions in a single transaction (bulk operations). Such APIs are recommended to be used in order to avoid the limitation.