Пользователи

Управление пользователями осуществляется с помощью двух ресурсов:

  • /users - ресурс для управления коллекцией пользователей
  • /users/:id - ресурс для управления конкретным пользователем с логином :id
Метод Ресурс Результат
POST /users создать пользователя
GET /users найти пользователей
GET /users/:id получить данные пользователя
POST /users/:id изменить данные пользователя
DELETE /users/:id удалить пользователя

Создание пользователя

Чтобы создать пользователя, необходимо выполнить запрос POST /users с JSON-документом в теле вида:

Поле Описание Обязателен Разрешенные значения
id Логин пользователя Да
Строчные и прописные латинские
буквы, цифры, дефис, нижний подчерк.
Длина: 3-20 символов.
“^[-\w]{3,20}$”
password Пароль Да
Любой печатный ASCII-символ.
Длина: 5-64 символов.n
“^[[:graph:]]{5,64}$”
email Почтовый адрес Да
Любой валидный email-адрес.
“^[\w+_.-]+@[\w.-]+\.[a-z]{2,5}$”
name Имя пользователя Нет
Любые печатные UTF8-символы,
пробел, дефис.
Длина: 3-50 символов.
“^[\p{L}’\.s\d-]{3,50}$”
data JSON-документ Нет
Валидный JSON документ
role Роль Да
administrator, advertiser,
publisher, moderator, publisher_guest
company Id организации Нет
Id существующей организации
“^[-\w]{3,20}$”

Значение поля role определяет перечень разрешенных действий пользователя.

Так пользователям с ролью administrator разрешено выполнение любых операций. Пользователям с ролью moderator разрешено модерировать баннеры, кроме того модераторы имеют read-only доступ к любому ресурсу. Пользователи с ролью publisher могут управлять площадками, а пользователи с ролью advertiser — создавать кампании и баннеры. Роль puplisher_guest работает аналогично роли publisher, но имеет read-only доступ.

Пример:

$ curl --request POST \
       --include \
       --user "admin:admin" \
       --header "Content-Type: application/json" \
       --data \
       '{
          "id":"alice",
          "password":"wonderland",
          "email":"alice@example.com",
          "name":"Alice",
          "role":"administrator"
        }' \
       --url http://api.example.com/users

HTTP/1.1 200 OK
Server: nginx/1.4.3
Date: Tue, 12 Nov 2013 07:05:07 GMT
Content-Type: application/json
Content-Length: 103
Connection: keep-alive
Location: http://api.example.com/users/alice

{
  "id":"alice",
  "password":"6d184e19d86d5bd517dca9b99dff3c17",
  "email":"alice@example.com",
  "name":"Alice",
  "data":null,
  "role":"administrator"
}

Только пользователи с ролью administrator могут создавать новых пользователей, не привязанных к организации (company: null).

Владелец организации может создавать новых членов своей организации.

Поиск пользователей

Чтобы получить список пользователей, необходимо выполнить запрос GET /users.

Пример:

$ curl --request GET \
       --include \
       --user "admin:admin" \
       --url http://api.example.com/users

HTTP/1.1 200 OK
Server: nginx/1.4.3
Date: Tue, 12 Nov 2013 07:36:56 GMT
Content-Type: application/json
Content-Length: 136
Connection: keep-alive

{
  "results": [
    {
      "id":"admin",
      "email":"admin@example.com",
      "name":"Chuck Norris",
      "role":"administrator",
      "data":null
    },
    {
      "id":"alice",
      "email":"alice@example.com",
      "name":"Alice",
      "role":"administrator",
      "data":null
    }
  ],
  "total_count": 2
}

Только администраторам разрешено выполнение этого вида запросов.

Получение данных пользователя

Чтобы получить данные пользователя, необходимо выполнить запрос GET /users/:id.

Пример:

$ curl --request GET \
       --include \
       --user "admin:admin" \
       --url http://api.example.com/users/admin

HTTP/1.1 200 OK
Server: nginx/1.4.3
Date: Tue, 12 Nov 2013 07:43:00 GMT
Content-Type: application/json
Content-Length: 64
Connection: keep-alive

{
  "id":"admin",
  "email":"admin@example.com",
  "name":"Chuck Norris",
  "role":"administrator",
  "data":null
}

Изменение данных пользователя

Чтобы изменить данные пользователя, необходимо выполнить запрос POST /users/:id.

Формат документа для обновления данных пользователя идентичен формату документа для создания пользователя. Если поле не указано или содержит литерал null, значение поля не будет обновлено.

Пример:

$ curl --request POST \
       --include \
       --user "admin:admin" \
       --header "Content-Type: application/json" \
       --data \
       '{
          "name":"Alice in Wonderland"
        }' \
       --url http://api.example.com/users/alice

HTTP/1.1 200 OK
Server: nginx/1.4.3
Date: Tue, 12 Nov 2013 07:44:16 GMT
Content-Type: application/json
Content-Length: 117
Connection: keep-alive

{
  "id":"alice",
  "password":"6d184e19d86d5bd517dca9b99dff3c17",
  "email":"alice@example.com",
  "name":"Alice in Wonderland",
  "role":"administrator",
  "data":null
}

Пользователь с ролью administrator может редактировать любой профиль. Другим пользователям разрешено редактировать только свой профиль.

Удаление пользователя

Чтобы удалить пользователя, необходимо выполнить запрос DELETE /users/:id.

Нельзя удалить пользователя admin.

Пример:

$ curl --request DELETE \
       --include \
       --user "admin:admin" \
       --url http://api.example.com/users/alice

HTTP/1.1 204 No Content
Server: nginx/1.4.3
Date: Tue, 12 Nov 2013 07:48:59 GMT
Content-Type: application/json
Content-Length: 0
Connection: keep-alive

Только пользователи с ролью administrator могут удалять пользователей.