Conceptual Overview

The basic kinds of resources provided by the API are Devices, Activities, and Time frames. The Users resource must also be considered in order to understand how to set up and control access to the resources.

Below is a simplified schema showing their interactions:

For a more comprehensive visual overview of the resources, we also provide a UML class diagram of the resources.

Users

Users represent the functions of the people using the API. Each user has a role, which defines what they are allowed to do on the API. On this API, all user-related endpoints are role-based. More information on users is provided below.

Devices

Devices represent the physical trackers that can generate data during a sport session. They are pre-registered on the API and must be claimed by a user before usage.

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 transferred to another manager, and the previous manager can still access device's preprocessed data produced during the time frame of his ownership.

A device needs to be activated to be used. Activation is done automatically when the first ownership starts. The device's ownership request and activation is done from the Device Activation webpage. A device should not have ongoing ownership to request an ownership, and conversely, have an ongoing ownership to release ownership. A manager can request a device's ownership if it has no ongoing ownership from another user. They will then become the owner of the device. A manager can release ownership of a device if they are the current owner of this device.

Activities

Activities represent the sport sessions, for example a soccer game. Activities are managed by users with manager role. Creating an activity require a configuration field named json. It contains a JSON document with a structured defined by the JSON schema given in the json_schema field. Values will be validated against the JSON schema.

The JsonSchema resource type is ready-only and managed by Insiders administrators. It is used to specify the metadata associated to a type of activity. Generally, there is one specific schema for each of sport. The schemas may be updated by Insiders administrators, usually to add fields. As for the rest of the API, such updates should not include breaking changes, with some exceptions in which the change will be communicated in advance. For more information on JSON Schema, read the documentation at https://json-schema.org/.

Time frames

Time frames links an athlete, a device and an activity together during a specified time frame. Time frames are managed by users with manager role.

Time frames along with activities are used by the platform to process the computed data produced by a Device, worn by an Athlete 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 a defined time frame can retrieve the computed data.

Similarly to activities, time frames require some sport-specific parameters that must be provided through a params object, specified by and validated against the schema provided in json_schema.