Getting started guide

Version : 1.0.0

This guide aim to explain how to use the ASI API through definitions and examples.

The API documentation is available on

A JSON schema guide is available on

First, the resources of this API are detailed.

Then, the user roles that this API support are explained, and what does this roles allow.

Then, it explain how theses users can authenticate themself and how an AMS can request users data using OAuth 2.0.


There are at this moment 4 category of resources.


Users reprensents the users of the API. Each user hase a role, which defines what he can do on this API. All user-related endpoints on this API are role-based. More informations on users in the next section.


Devices represents the ASI devices that can produce data during a sport session. Devices are managed by ASI administrators.

A device can be owned by a manager. Once device's owner, the manager can access the preprocessed data produced by this device. Ownership is time-based, so that a device can be transfered to another manager, and the previous manager still can access device's preprocessed data produced during his ownership.

A device need to be activated to be used. Activation is done automatically when the first ownership start. A device should not have ongoing ownership to request an ownership, and, conversely have an ongoing ownership to release ownership. A manager can request ownership of a device if it has no ongoing ownership for another user. He will become the owner of the device. A manager can release ownership of a device if he is the current owner of this device.


Activies represent the sport sessions, for example a football match. Activities are managed by manager users. Creating an activity require a configuration field named json. It contains a JSON document with values required by referenced JSON schema. Values will be validated against the JSON schema.

JsonSchema is a type resource managed by ASI administrators users only. It defines the mandatory metadata that an activity should have. There is generally one JSON schema per sport type. When an administrator add mandatory metadata, a new JsonSchema will be created, reprensenting a new version. For more informations on JSON Schema, read the documentation at

Time frames

Time frames link an athlete, a device and an activity together during a time frame. Time frames are managed by manager users.

Time frames along with activities are used by the platform to compute the computed data produced by a device, worn by a user participating to an activity. Managers can retrieve computed data given a time frame identifier. Only the managers who had/have READ permission on athlete data during the time frame can retrieve the computed data.


There are 3 types of users :

Unauthenticated user can only create new manager or athlete accounts.


Administrator user type is an type for the ASI administrators accounts.


Athlete user type is a type for athletes accounts. Their profile contains basic data, such as first name and last name and physiological data, such as weight, height, maximum heart rate, etc. Anyone can create a athlete account.

Once logged in, an ahtlete can


Manager user type is type for manager accounts. Their profile contains basic data such as first name and last name. Anyone can create a manager account.

Once logged in, a manager can

OAuth 2.0

Authentication is done through OAuth 2.0. That means requests to the API require a Bearer token in the Authorization header. The supported authorizations grants are Authorization Code and Resource Owner Password Credentials.

In the case of Authorization Code grant, AMS should request user authorization to access their data on the platform. User will be redirected to the ASI API login page, and once logged in, they can authorize or deny the AMS.

AMS client registration

Registration of a new AMS is done only by ASI administrators. AMS Developpers should follow the following step to register their AMS.

  1. AMS developpers ask an ASI administrators to create a new AMS client application on the API, specifying desired grant
  2. AMS give a callback URL where the API will return the authorization code (only in the cas of Authorization Code grant)
  3. ASI administrators gives the AMS developpers the Client ID and Client Secret corresponding to the newly created AMS client application
  4. AMS developpers implements their client with the following configuration

AMS client configurations

Key Value
Grant Type Authorization Code or Resource Owner Password Credentials
Callback URL (specific to the AMS client)
Authorize URL /oauth2/authorize/
Access token URL /oauth2/token/
Client ID (client ID of the AMS client)
Client Secret (client Secret of the AMS client)
Scope all
Client Authentication Basic Auth header

If needed, the Revoke token URL is /oauth2/revoke-token/.

OAuth specification defines scopes. In this API, only one scope is registered : all. There is no granularity on the user's data that the client can access.

Note the trailing slash in the URLs

Live streaming data

Computed data

The platform allows manager and administrator users to live stream computed data for an ongoing activity, given a timeframe identifier. Live streaming is done through WebSocket (wss://). The path is /api/ws/computed-data/{activity}/{timeframe}/.

The platform allows all incoming connections, but require the client to sent an authentication message, containing an access token. This message must be the first one send through this socket by the client, and it must be done before a timeout, configured to 3 seconds.

If the token allows the platform to authenticate a known manager or administrator user, then data will be live streamed. Otherwise, the connection is closed.

Manager user must have a read permission on the athlete linked to the time frame to live stream their data.

The expected authentication message is a JSON document containing a single token key.

{ "token": "<access_token>" }

Computed data messages are JSON document containing the computed data. For example:

{ "total_distance": 83.20118419047552, "accelerations": { "threshold_2": { "threshold": 3, "values": [] }, "threshold_1": { "threshold": 2, "values": [] } }, "decelerations": { "threshold_2": { "threshold": 3, "values": [] }, "threshold_1": { "threshold": 2, "values": [] } }, "max_speed": 1.1826, "average_speed": 0.20038889929742307, "last_timestamp": 1597924127900.0 // other data }

Note: computed data may vary depending on the activity and timeframe configurations.

Computed data by activity

It is also possible to subscribe to all computed data concerning an activity. In that case the path is /api/ws/computed-data/{activity}/. Manager is allowed to stream theses data if he's allowed to stream every activity's timeframes computed data.

Computed data are still computed for each timeframe, so messages received through this socket concerns only one timeframe by message. Each message has a timeframe key containing the timeframe id for which computed data are computed.

For example:

{ // Time frame id "timeframe": 86, // Computed data for this timeframe "data": { "total_distance": 83.20118419047552, "accelerations": { "threshold_2": { "threshold": 3, "values": [] }, "threshold_1": { "threshold": 2, "values": [] } }, "decelerations": { "threshold_2": { "threshold": 3, "values": [] }, "threshold_1": { "threshold": 2, "values": [] } }, "max_speed": 1.1826, "average_speed": 0.20038889929742307, "last_timestamp": 1597924127900.0 } }

Preprocessed data

Similary to computed data, managers can also subscribe to a websocket stream of preprocessed data for a given device. The path is /api/ws/preprocessed-data/{device}/.

Manager user must be the device owner when he subscribe to the websocket

Authentication works the same as with computed data, previously explained.


In this scenario, a manager called A use the platform to create an activity and two time frames prior to a tennis match, where athletes B and C play against each other.

First, A should activate the devices used in this match.

A send a POST request to /api/v1/devices/1/take-ownership/ to own the device 1.

A send a POST request to /api/v1/devices/2/take-ownership/ to own the device 2.

Both B and C should give write permission to manager A to let A create time frame related to them. B send POST request to /api/v1/athletes/2/managers/2/permissions/ (the first 2 is athlete B's ID, the second 2 is manager A's ID) with the following JSON body to give write permission to A for the entire year 2020. C do the same with his ID in the URL.

{ "start_time": "2020-01-01T00:00:00.000Z", "expiration_time": "2020-12-31T23:59:59.000Z", "permission": "WRITE" }

B and C can also give read permission to manager A to let A retrieve or stream their (computed) data. For that, they the same request as for write, but with value READ instead of WRITE at key permission in the JSON body.

A send a POST request to /api/v1/activities/ with the following JSON body to create the activity.

{ "name": "Tennis match of 30 may 2020 at Wimbledon", "json": {"sport":"tennis","type":"match"}, "json_schema": 2, // JsonSchema ID correspondig to tennis "owner": 1 // ID of manager A }

A send a POST request to /api/v1/timeframes/ with the following JSON body to create the time frame for athlete B wearing device 1, starting at 20:00 and ending at 22:00.

{ "start_time": "2020-05-30T20:00:00.000Z", "end_time": "2020-05-30T22:00:00.000Z", "params": {}, // Seed doc for examples "device": 1, // ID of device worn by athlete B "activity": 1, // ID of previously created activity "athlete": 2, // ID of athelte B "owner": 1, // ID of manager A "json_schema": 4 // ID of json schema }

A send a POST request to /api/timeframes/ with the following JSON body to create the time frame for athlete C wearing device 2, starting at 20:00 and ending at 22:00.

{ "start_time": "2020-05-30T20:00:00.000Z", "end_time": "2020-05-30T22:00:00.000Z", "params": {}, // Seed doc for examples "device": 2, // ID of device worn by athlete C "activity": 1, // ID of previously created activity "athlete": 3, // ID of athelte C "owner": 1, // ID of manager A "json_schema": 4 // ID of json schema }

As A has read permission on athletes B and C, he can live stream the compted data of the athletes, through WebSocket. For computed data of athlete B, A can open a WebSocket on /api/v1/ws/computed-data/1/2/. 1 is the activity ID, and 2 is athlete B's time frame ID.