Users¶

GET /api/users¶

Get all users (regardless their account status), if authenticated user has admin rights.

It returns user preferences only for authenticated user.

Scope: users:read

Example request:

without parameters:

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

with some query parameters:

GET /api/users?order_by=workouts_count&par_page=5  HTTP/1.1
Content-Type: application/json

Example response:

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

{
  "data": {
    "users": [
      {
        "admin": true,
        "bio": null,
        "birth_date": null,
        "created_at": "Sun, 14 Jul 2019 14:09:58 GMT",
        "email": "admin@example.com",
        "first_name": null,
        "is_admin": true,
        "imperial_units": false,
        "language": "en",
        "last_name": null,
        "location": null,
        "nb_sports": 3,
        "nb_workouts": 6,
        "picture": false,
        "records": [
          {
            "id": 9,
            "record_type": "AS",
            "sport_id": 1,
            "user": "admin",
            "value": 18,
            "workout_date": "Sun, 07 Jul 2019 08:00:00 GMT",
            "workout_id": "hvYBqYBRa7wwXpaStWR4V2"
          },
          {
            "id": 10,
            "record_type": "FD",
            "sport_id": 1,
            "user": "admin",
            "value": 18,
            "workout_date": "Sun, 07 Jul 2019 08:00:00 GMT",
            "workout_id": "hvYBqYBRa7wwXpaStWR4V2"
          },
          {
            "id": 13,
            "record_type": "HA",
            "sport_id": 1,
            "user": "Sam",
            "value": 43.97,
            "workout_date": "Sun, 07 Jul 2019 08:00:00 GMT",
            "workout_id": "hvYBqYBRa7wwXpaStWR4V2"
          },
          {
            "id": 11,
            "record_type": "LD",
            "sport_id": 1,
            "user": "admin",
            "value": "1:01:00",
            "workout_date": "Sun, 07 Jul 2019 08:00:00 GMT",
            "workout_id": "hvYBqYBRa7wwXpaStWR4V2"
          },
          {
            "id": 12,
            "record_type": "MS",
            "sport_id": 1,
            "user": "admin",
            "value": 18,
            "workout_date": "Sun, 07 Jul 2019 08:00:00 GMT",
            "workout_id": "hvYBqYBRa7wwXpaStWR4V2"
          }
        ],
        "sports_list": [
            1,
            4,
            6
        ],
        "timezone": "Europe/Paris",
        "total_distance": 67.895,
        "total_duration": "6:50:27",
        "username": "admin",
        "weekm": false
      },
      {
        "admin": false,
        "bio": null,
        "birth_date": null,
        "created_at": "Sat, 20 Jul 2019 11:27:03 GMT",
        "email": "sam@example.com",
        "first_name": null,
        "is_admin": false,
        "language": "fr",
        "last_name": null,
        "location": null,
        "nb_sports": 0,
        "nb_workouts": 0,
        "picture": false,
        "records": [],
        "sports_list": [],
        "timezone": "Europe/Paris",
        "total_distance": 0,
        "total_duration": "0:00:00",
        "username": "sam"
      }
    ]
  },
  "status": "success"
}

Query Parameters:

page (integer) – page if using pagination (default: 1)
per_page (integer) – number of users per page (default: 10, max: 50)
q (string) – query on user name
order (string) – sorting order: asc, desc (default: asc)
order_by (string) – sorting criteria: username, created_at, workouts_count, admin, is_active (default: username)

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

GET /api/users/(user_name)¶

Get single user details. Only user with admin rights can get other users details.

It returns user preferences only for authenticated user.

Scope: users:read

Example request:

GET /api/users/admin HTTP/1.1
Content-Type: application/json

Example response:

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

{
  "data": [
    {
      "admin": true,
      "bio": null,
      "birth_date": null,
      "created_at": "Sun, 14 Jul 2019 14:09:58 GMT",
      "email": "admin@example.com",
      "first_name": null,
      "imperial_units": false,
      "is_admin": true,
      "language": "en",
      "last_name": null,
      "location": null,
      "nb_sports": 3,
      "nb_workouts": 6,
      "picture": false,
      "records": [
        {
          "id": 9,
          "record_type": "AS",
          "sport_id": 1,
          "user": "admin",
          "value": 18,
          "workout_date": "Sun, 07 Jul 2019 08:00:00 GMT",
          "workout_id": "hvYBqYBRa7wwXpaStWR4V2"
        },
        {
          "id": 10,
          "record_type": "FD",
          "sport_id": 1,
          "user": "admin",
          "value": 18,
          "workout_date": "Sun, 07 Jul 2019 08:00:00 GMT",
          "workout_id": "hvYBqYBRa7wwXpaStWR4V2"
        },
        {
          "id": 13,
          "record_type": "HA",
          "sport_id": 1,
          "user": "Sam",
          "value": 43.97,
          "workout_date": "Sun, 07 Jul 2019 08:00:00 GMT",
          "workout_id": "hvYBqYBRa7wwXpaStWR4V2"
        },
        {
          "id": 11,
          "record_type": "LD",
          "sport_id": 1,
          "user": "admin",
          "value": "1:01:00",
          "workout_date": "Sun, 07 Jul 2019 08:00:00 GMT",
          "workout_id": "hvYBqYBRa7wwXpaStWR4V2"
        },
        {
          "id": 12,
          "record_type": "MS",
          "sport_id": 1,
          "user": "admin",
          "value": 18,
          "workout_date": "Sun, 07 Jul 2019 08:00:00 GMT",
          "workout_id": "hvYBqYBRa7wwXpaStWR4V2"
        }
      ],
      "sports_list": [
          1,
          4,
          6
      ],
      "timezone": "Europe/Paris",
      "total_distance": 67.895,
      "total_duration": "6:50:27",
      "username": "admin"
    }
  ],
  "status": "success"
}

Parameters:

user_name (integer) – user name

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
404 Not Found –
- user does not exist

GET /api/users/(user_name)/picture¶

get user picture

Example request:

GET /api/users/admin/picture HTTP/1.1
Content-Type: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: image/jpeg

Parameters:

user_name (integer) – user name

Status Codes:

200 OK – success
404 Not Found –
- user does not exist
- No picture.

PATCH /api/users/(user_name)¶

Update user account.

add/remove admin rights (regardless user account status)
reset password (and send email to update user password, if sending enabled)
update user email (and send email to new user email, if sending enabled)
activate account for an inactive user

Only user with admin rights can modify another user.

Scope: users:write

Example request:

PATCH /api/users/<user_name> HTTP/1.1
Content-Type: application/json

Example response:

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

{
  "data": [
    {
      "admin": true,
      "bio": null,
      "birth_date": null,
      "created_at": "Sun, 14 Jul 2019 14:09:58 GMT",
      "email": "admin@example.com",
      "first_name": null,
      "imperial_units": false,
      "is_active": true,
      "language": "en",
      "last_name": null,
      "location": null,
      "nb_workouts": 6,
      "nb_sports": 3,
      "picture": false,
      "records": [
        {
          "id": 9,
          "record_type": "AS",
          "sport_id": 1,
          "user": "admin",
          "value": 18,
          "workout_date": "Sun, 07 Jul 2019 08:00:00 GMT",
          "workout_id": "hvYBqYBRa7wwXpaStWR4V2"
        },
        {
          "id": 10,
          "record_type": "FD",
          "sport_id": 1,
          "user": "admin",
          "value": 18,
          "workout_date": "Sun, 07 Jul 2019 08:00:00 GMT",
          "workout_id": "hvYBqYBRa7wwXpaStWR4V2"
        },
        {
          "id": 13,
          "record_type": "HA",
          "sport_id": 1,
          "user": "Sam",
          "value": 43.97,
          "workout_date": "Sun, 07 Jul 2019 08:00:00 GMT",
          "workout_id": "hvYBqYBRa7wwXpaStWR4V2"
        },
        {
          "id": 11,
          "record_type": "LD",
          "sport_id": 1,
          "user": "admin",
          "value": "1:01:00",
          "workout_date": "Sun, 07 Jul 2019 08:00:00 GMT",
          "workout_id": "hvYBqYBRa7wwXpaStWR4V2"
        },
        {
          "id": 12,
          "record_type": "MS",
          "sport_id": 1,
          "user": "admin",
          "value": 18,
          "workout_date": "Sun, 07 Jul 2019 08:00:00 GMT",
          "workout_id": "hvYBqYBRa7wwXpaStWR4V2"
        }
      ],
      "sports_list": [
          1,
          4,
          6
      ],
      "timezone": "Europe/Paris",
      "total_distance": 67.895,
      "total_duration": "6:50:27",
      "username": "admin"
    }
  ],
  "status": "success"
}

Parameters:

user_name (string) – user name

Request JSON Object:

activate (boolean) – activate user account
admin (boolean) – does the user have administrator rights
new_email (boolean) – new user email
reset_password (boolean) – reset user password

Request Headers:

Authorization – OAuth 2.0 Bearer Token

Status Codes:

200 OK – success
400 Bad Request –
- invalid payload
- valid email must be provided
- new email must be different than current email
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 – user does not exist
500 Internal Server Error – error, please try again or contact the administrator

DELETE /api/users/(user_name)¶

Delete a user account.

A user can only delete his own account.

An admin can delete all accounts except his account if he’s the only one admin.

Scope: users:write

Example request:

DELETE /api/users/john_doe HTTP/1.1
Content-Type: application/json

Example response:

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

Parameters:

user_name (string) – user name

Request Headers:

Authorization – OAuth 2.0 Bearer Token

Status Codes:

204 No Content – user account 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 can not delete your account, no other user has admin rights
404 Not Found – user does not exist
500 Internal Server Error – error, please try again or contact the administrator