Équipements¶

GET /api/equipments¶

Obtenir tous les équipements d'un utilisateur. Seul le propriétaire de l'équipement peut voir son équipement.

Un utilisateur suspendu peut accéder à ce point d'accès.

Scope : equipments:read

Exemple de requête :

GET /api/equipments HTTP/1.1
Content-Type: application/json

avec quelques paramètres de requête (obtenir tous les équipements de type "Shoes")

GET /api/equipment?equipment_type_id=1  HTTP/1.1

Exemple de réponse :

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "equipments": [
      {
        "creation_date": "Tue, 21 Mar 2023 06:08:06 GMT",
        "default_for_sport_ids": [],
        "description": "The first shoes added to FitTrackee",
        "equipment_type": {
          "id": 1,
          "is_active": true,
          "label": "Shoe"
        },
        "id": "2UkrViYShoAkg8qSUKnUS4",
        "is_active": true,
        "label": "My shoes",
        "total_distance": 0.0,
        "total_duration_in_hours": 0,
        "user_id": 1,
        "workouts_count": 0
    },
    {
        "creation_date": "Tue, 21 Mar 2023 06:08:29 GMT",
        "default_for_sport_ids": [],
        "description": "The second shoes added to FitTrackee",
        "equipment_type": {
          "id": 1,
          "is_active": true,
          "label": "Shoe"
        },
        "id": "2UkrViYShoAkg8qSUKnUS4",
        "is_active": true,
        "label": "My shoes 2",
        "total_distance": 0.0,
        "total_duration_in_hours": 0,
        "user_id": ,
        "workouts_count": 0
        }
      ]
    }
  },
  "status": "success"
}

Paramètres de la requête:

equipment_type_id (integer) -- id du type d'équipement

Entêtes de la requête:

Authorization -- Jeton 'OAuth 2.0 Bearer'

Codes d'état:

200 OK -- succès
401 Unauthorized --
- provide a valid auth token
- signature expired, please log in again
- invalid token, please log in again
403 Forbidden --
- you do not have permissions

GET /api/equipments/(string: equipment_short_id)¶

Obtenir un équipement. Seul le propriétaire de l'équipement peut voir son équipement.

Un utilisateur suspendu peut accéder à ce point d'accès.

Scope : equipments:read

Exemple de requête :

GET /api/equipments/2UkrViYShoAkg8qSUKnUS4 HTTP/1.1
Content-Type: application/json

Exemple de réponse :

succès

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "equipments": [
      {
        "creation_date": "Tue, 21 Mar 2023 06:08:06 GMT",
        "default_for_sport_ids": [],
        "description": "Another piece of equipment",
        "equipment_type": {
          "id": 1,
          "is_active": true,
          "label": "Shoe"
        },
        "id": "2UkrViYShoAkg8qSUKnUS4",
        "is_active": true,
        "label": "Other user Equipment",
        "total_distance": 0.0,
        "total_duration_in_hours": 0,
        "user_id": 2,
        "workouts_count": 0
      }
    ]
  },
  "status": "success"
}

équipement non trouvé :

HTTP/1.1 404 NOT FOUND
Content-Type: application/json

{
  "data": {
    "equipments": []
  },
  "status": "not found"
}

Paramètres:

equipment_short_id (string) -- id court de l'équipement

Entêtes de la requête:

Authorization -- Jeton 'OAuth 2.0 Bearer'

Codes d'état:

200 OK -- succès
401 Unauthorized --
- provide a valid auth token
- signature expired, please log in again
- invalid token, please log in again
403 Forbidden --
- you do not have permissions
404 Not Found -- equipment not found

POST /api/equipments¶

Créer un nouvel équipement.

Scope : equipments:write

Exemple de requête :

POST /api/equipments HTTP/1.1
Content-Type: application/json

Exemple de réponse :

succès

HTTP/1.1 201 CREATED
Content-Type: application/json

{
  "data": {
    "equipments": [
      {
        "creation_date": "Tue, 21 Mar 2023 06:08:29 GMT",
        "default_for_sport_ids": [],
        "description": null,
        "equipment_type": {
          "id": 1,
          "is_active": true,
          "label": "Shoe"
        },
        "id": "2UkrViYShoAkg8qSUKnUS4",
        "is_active": true,
        "label": "New equipment from API",
        "total_distance": 0.0,
        "total_duration_in_hours": 0,
        "user_id": 1,
        "workouts_count": 0
      }
    ]
  },
  "status": "created"
}

équipement de type "Autres" dépassant la limite maximale, dans le cas où d'autres équipements de type "Autres" sont déjà associés à des sports

HTTP/1.1 400 BAD REQUEST
Content-Type: application/json

{
  "message": "a maximum of 5 pieces of Misc equipment can be added",
  "sport_ids": [1],
  "status": "limit_exceeded"
}

Object JSON de requête:

label (string) -- un label bref (moins de 50 caractères) pour l'équipement
equipment_type (integer) -- l'id d'un type d'équipement (il doit être actif)
description (string) -- une description (éventuellement plus longue) de l'équipement (limitée à 200 caractères, facultatif)
is_active (boolean) -- si cet équipement est actuellement actif ou non (par défaut : true)
default_for_sport_ids (array of integers) -- les id des sports par défaut à utiliser pour cet équipement, non obligatoires. Note : Si le sport est déjà associé à un équipement par défaut, celui-ci est remplacé, sauf dans le cas d'un équipement de type "Autres", auquel cas il est ajouté. Si le sport a déjà 5 équipements de type "Autres", un message d'erreur est renvoyé.
visibility (string) -- niveau de visibilité (public, followers_only, private), optionnel (valeur par défaut : private)

Entêtes de la requête:

Authorization -- Jeton 'OAuth 2.0 Bearer'

Codes d'état:

201 Created -- équipement créé
400 Bad Request --
- the 'label' and 'equipment_type_id' parameters must be provided
- equipment already exists with the same label
- label exceeds 50 characters
- invalid equipment type id
- equipment type is inactive
- sport (id <sport_id>) does not exist
- invalid sport '<sport_label>' for equipment type '<equipment_type_label>'
- a maximum of 5 pieces of Misc equipment can be added
401 Unauthorized --
- provide a valid auth token
- signature expired, please log in again
- invalid token, please log in again
403 Forbidden --
- you do not have permissions
- you do not have permissions, your account is suspended
404 Not Found -- equipment not found
500 Internal Server Error -- Error during equipment save

PATCH /api/equipments/(string: equipment_short_id)¶

Modifier un équipement. Permet à un utilisateur de modifier le label, la description, le type ou le statut actif d'un de ses équipements.

Le changement de type d'un équipement supprimera toutes les associations existantes à des séances pour cet équipement et les sports définis par défaut.

Scope : equipments:write

Exemple de requête :

PATCH /api/equipments/QRj7BY6H2iYjSV8sersFgV HTTP/1.1
Content-Type: application/json

Exemple de réponses :

succès

HTTP/1.1 200 OK
Content-Type: application/json

  {
    "data": {
      "equipments": [
        {
          "creation_date": "Tue, 21 Mar 2023 06:28:10 GMT",
          "default_for_sport_ids": [],
          "description": "Change bike to shoes",
          "equipment_type": {
            "id": 1,
            "is_active": true,
            "label": "Shoe"
          },
          "id": "QRj7BY6H2iYjSV8sersFgV",
          "is_active": true,
          "label": "Updated bike",
          "total_distance": 0.0,
          "total_duration_in_hours": 0,
          "user_id": 1,
          "workouts_count": 0
        }
      ]
    },
    "status": "success"
  }

équipement non trouvé :

HTTP/1.1 404 NOT FOUND
Content-Type: application/json

{
  "data": {
    "equipments": []
  },
  "status": "not found"
}

équipement de type "Autres" dépassant la limite maximale, dans le cas où d'autres équipements de type "Autres" sont déjà associés à des sports

HTTP/1.1 400 BAD REQUEST
Content-Type: application/json

{
  "message": "a maximum of 5 pieces of Misc equipment can be added",
  "sport_ids": [1],
  "status": "limit_exceeded"
}

Paramètres:

equipment_short_id (string) -- id court de l'équipement

Object JSON de requête:

label (string) -- un label bref (moins de 50 caractères) pour l'équipement
equipment_type_id (int) -- l'id d'un type d'équipement (il doit être actif)
description (string) -- une description (éventuellement plus longue) de l'équipement (limitée à 200 caractères, facultatif)
is_active (boolean) -- si cet équipement est actuellement actif ou non (par défaut : true)
default_for_sport_ids (array of integers) -- les id des sports par défaut à utiliser pour cet équipement. Note : Si le sport est déjà associé à un équipement par défaut, celui-ci est remplacé, sauf dans le cas d'un équipement de type "Autres", auquel cas il est ajouté. Si le sport a déjà 5 équipements de type "Autres", un message d'erreur est renvoyé.
visibility (string) -- niveau de visibilité (public, followers_only, private)

Entêtes de la requête:

Authorization -- Jeton 'OAuth 2.0 Bearer'

Codes d'état:

200 OK -- équipement mis à jour
400 Bad Request --
- no request data was supplied
- no valid parameters supplied
- equipment already exists with the same label
- label exceeds 50 characters
- invalid equipment type id
- equipment type is inactive
- sport (id <sport_id>) does not exist
- invalid sport '<sport_label>' for equipment type '<equipment_type_label>'
- a maximum of 5 pieces of Misc equipment can be added
401 Unauthorized --
- provide a valid auth token
- signature expired, please log in again
- invalid token, please log in again
403 Forbidden --
- you do not have permissions
- you do not have permissions, your account is suspended
404 Not Found -- equipment not found
500 Internal Server Error -- Error during equipment update

POST /api/equipments/(string: equipment_short_id)/refresh¶

Recalcule les totaux de l'équipement (dans le cas où les valeurs seraient incorrectes).

Scope : equipments:write

Exemple de requête :

POST /api/equipments/QRj7BY6H2iYjSV8sersFgV/refresh HTTP/1.1
Content-Type: application/json

Exemple de réponse :

HTTP/1.1 200 OK
Content-Type: application/json

  {
    "data": {
      "equipments": [
        {
          "creation_date": "Tue, 21 Mar 2023 06:28:10 GMT",
          "default_for_sport_ids": [],
          "description": "My Shoes",
          "equipment_type": {
            "id": 1,
            "is_active": true,
            "label": "Shoe"
          },
          "id": "QRj7BY6H2iYjSV8sersFgV",
          "is_active": true,
          "label": "Updated bike",
          "total_distance": 6.0,
          "total_duration_in_hours": 1,
          "user_id": 1,
          "workouts_count": 1
        }
      ]
    },
    "status": "success"
  }

Entêtes de la requête:

Authorization -- Jeton 'OAuth 2.0 Bearer'

Codes d'état:

200 OK -- équipement mis à jour
401 Unauthorized --
- provide a valid auth token
- signature expired, please log in again
- invalid token, please log in again
403 Forbidden --
- you do not have permissions
- you do not have permissions, your account is suspended
404 Not Found -- equipment not found
500 Internal Server Error -- Error during equipment save

DELETE /api/equipments/(string: equipment_short_id)¶

Supprimer un équipement

Un utilisateur ne peut supprimer que son propre équipement, et seulement s'il n'y a pas de séances associées à cet équipement (à moins que la suppression ne soit forcée). Si l'équipement était associé à des séances et que la suppression est forcée, l'association entre cet équipement et ces séances sera supprimée. Si cet équipement était un équipement par défaut pour n'importe quel sport, la préférence sera mise à jour.

Scope : equipments:write

Exemple de requête :

DELETE /api/equipments/QRj7BY6H2iYjSV8sersFgV HTTP/1.1
Content-Type: application/json

Exemple de réponse :

HTTP/1.1 204 NO CONTENT
Content-Type: application/json

Paramètres:

equipment_short_id (string) -- id court de l'équipement

Paramètres de la requête:

force -- si fourni en tant qu'argument (aucune valeur requise), cela forcera la suppression de l'équipement et l'enlèvera des séances associées

Entêtes de la requête:

Authorization -- Jeton 'OAuth 2.0 Bearer'

Codes d'état:

204 No Content -- équipement supprimé
401 Unauthorized --
- provide a valid auth token
- signature expired, please log in again
- invalid token, please log in again
403 Forbidden --
- you do not have permissions
- you do not have permissions, your account is suspended
- you cannot delete equipment that has workouts associated with it without 'force' parameter
404 Not Found -- equipment not found
500 Internal Server Error -- error, please try again or contact the administrator