Equipments¶

GET /api/equipments¶

Get all user equipments. Only the equipment owner can see his equipment.

Scope: equipments:read

Example request:

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

with some query parameters (get all equipment of type “Shoes”)

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

Example response:

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": "0:00:00",
        "total_moving": "0:00:00",
        "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": "0:00:00",
        "total_moving": "0:00:00",
        "user_id": ,
        "workouts_count": 0
        }
      ]
    }
  },
  "status": "success"
}

Query Parameters:

equipment_type_id (integer) – equipment type id

Request Headers:

Authorization – OAuth 2.0 Bearer Token

Status Codes:

200 OK – success
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)¶

Get an equipment item. Only the equipment owner can see his equipment.

Scope: equipments:read

Example request:

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

Example response:

success

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": "0:00:00",
        "total_moving": "0:00:00",
        "user_id": 2,
        "workouts_count": 0
      }
    ]
  },
  "status": "success"
}

equipment not found

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

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

Parameters:

equipment_short_id (string) – equipment short id

Request Headers:

Authorization – OAuth 2.0 Bearer Token

Status Codes:

200 OK – success
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¶

Post a new piece of equipment.

Scope: equipments:write

Example request:

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

Example response:

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": "0:00:00",
        "total_moving": "0:00:00",
        "user_id": 1,
        "workouts_count": 0
      }
    ]
  },
  "status": "created"
}

Request JSON Object:

label (string) – a brief (less than 50 characters) label for the piece of equipment
equipment_type (integer) – the ID for an equipment type (it must be active)
description (string) – a (perhaps longer) description of the equipment (limited to 200 characters, optional)
is_active (boolean) – whether or not this equipment is currently active (default: true)
default_for_sport_ids (array of integers) – the default sport ids to use for this equipment, not mandatory

Request Headers:

Authorization – OAuth 2.0 Bearer Token

Status Codes:

201 Created – equipment created
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>'
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
500 Internal Server Error – Error during equipment save

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

Update a piece of equipment. Allows a user to change one of their equipment’s label, description, type or active status.

Changing equipment type will remove all existing workouts associations for that piece of equipment and default sports.

Scope: equipments:write

Example request:

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

Example responses:

success

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": "0:00:00",
          "total_moving": "0:00:00",
          "user_id": 1,
          "workouts_count": 0
        }
      ]
    },
    "status": "success"
  }

equipment not found

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

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

Parameters:

equipment_short_id (string) – equipment short id

Request JSON Object:

label (string) – a brief (less than 50 characters) label for the piece of equipment
equipment_type_id (int) – the ID for an equipment type (it must be active)
description (string) – a (perhaps longer) description of the equipment (limited to 200 characters, optional)
is_active (boolean) – whether or not this equipment is currently active (default: true)
default_for_sport_ids (array of integers) – the default sport ids to use for this equipment

Request Headers:

Authorization – OAuth 2.0 Bearer Token

Status Codes:

200 OK – equipment updated
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>'
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
500 Internal Server Error – Error during equipment update

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

Refresh equipment totals (in case values are incorrect).

Scope: equipments:write

Example request:

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

Example response:

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": "1:10:00",
          "total_moving": "1:00:00",
          "user_id": 1,
          "workouts_count": 1
        }
      ]
    },
    "status": "success"
  }

Request Headers:

Authorization – OAuth 2.0 Bearer Token

Status Codes:

200 OK – equipment updated
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
500 Internal Server Error – Error during equipment save

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

Delete a piece of equipment.

A user can only delete their own equipment, and only if there are no workouts associated with that equipment (unless forced). If equipment was associated with any workouts and deletion is forced, the association between this equipment and those workouts will be removed. If this equipment was a default for any sport, that default will be removed (set to NULL).

Scope: equipments:write

Example request:

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

Example response:

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

Parameters:

equipment_short_id (string) – equipment short id

Query Parameters:

force – if supplied as argument (no value required), will force deletion of the equipment and remove that equipment from associated workouts

Request Headers:

Authorization – OAuth 2.0 Bearer Token

Status Codes:

204 No Content – equipment deleted
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 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