Equipments

GET /api/equipments

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

Suspended user can access this endpoint.

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:
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.

Suspended user can access this endpoint.

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:
Status Codes:
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

  • visibility (string) – visibility level (public, followers_only, private), not mandatory (default value: private)

Request Headers:
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

    • 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)

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

  • visibility (string) – visibility level (public, followers_only, private)

Request Headers:
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

    • 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

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:
Status Codes:
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:
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 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