Getting started guide

Version : 0.1.14

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

The API documentation is available on https://api.asi.swiss/doc/.

A JSON schema guide is available on https://api.asi.swiss/doc/jsonschema_guide.html.

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.

Resources

There are at this moment 4 category of resources.

Users

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

Devices represents the ASI Devices that can produce data during a sport session. Devices are managed by administrators, but manufacturer users can also (and only) create devices.

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.

Devices can be activated or deactivated. A device should be deactivated to request activation, and activated to request deactivation. A manager can activate a device if it has no owner at this moment (he will become the owner) or if the current owner is the manager itself. A manager can deactivate a device if he is the owner of this device at this moment. Any administrator can activate or deactivate a device.

Activities

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

JsonSchema is a resource managed by administrator users only. It defines the mandatory metadata that an activity should have. There is generally one JsonSchema 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 https://json-schema.org/.

Time frames

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

Time frames along with activities are used by the platform to compute the computed data associated to a user participating to an activity. Managers and administrators 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 retrive the computed data.

Users

There are 4 types of users :

Unauthenticated user can only create new manager or athlete accounts.

Administrators

Administrator user type is an account for the ASI administrator. They do not have attached profile.

Once logged in, an administrator can

Athletes

Athlete user type is an accont for athletes. Their profile contain 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

Managers

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

Once logged in, a manager can

Manufacturers

Manufacturers user type is an account for a manufacturer. Their profile contain the name and address of the manufacturer.

Once logged in, a manufacturer 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 implemented authorization grant is Authorization Code grant.

AMS should request user authorization to access their data on the platform. User will be redirected to the 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 admin to create a new AMS client application on the API
  2. AMS give a callback URL where the API will return the authorization code
  3. ASI Admin give 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 configurations

AMS client configurations

Key Value
Grant Type Authorization Code
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 connection, 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_id}/.

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

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

Example

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 PUT request to /api/devices/1/activate/ to activate and own the device 1.

A send a PUT request to /api/devices/2/activate/ to activate and 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/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/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/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", "player_position": "", "params": {}, // Seed doc for examples "player_number": 1, "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", "player_position": "", "params": {}, // Seed doc for examples "player_number": 1, "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/ws/computed-data/1/2/. 1 is the activity ID, and 2 is athlete B's time frame ID.