API управления настройками уведомлений о событиях

Общие обозначения и договорености

• {sso_host} - базовый адрес сервера SSO, например sso.rooxteam.com

• В случае успешного выполения запроса, HTTP статус ответа будет 20Х, в случае проблем, код статуса будет - 4XX-5XX, в теле ответа будет описание ошибки.

• При запросах к API ошибки со статусом 503 всегда приходят в HTML.

• Все методы сервиса поддерживают @me-нотацию для ID пользователя. При этом в качестве ID будет использоваться имя пользователя из переданного для авторизации токена.

Авторизация

Сервис поддерживает авторизацию двумя способами:

1. через системный токен

2. через пользовательский (только редактирование собственного пользователя @me).

Токен доступа передается стандартным способом в cookie с заданным в настройках решения именем или в заголовке Authorization. В примерах приведен вариант с передачей токена в заголовке.

Ошибки

В случае использования недопустимых параметров, будет возвращен ответ с HTTP статусом 400.

В случае ошибки авторизации, будет возвращен ответ с HTTP статусом 401.

Пример ответа с ошибкой

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8
Content-Length: 47

{
  "error": {
    "code": 401,
    "message": "Unauthorized"
  }
}

Настройка отправки уведомлений о событиях

Флаг устанавливает поведение отправки уведомлений о событии для пользователя {principal}

Установка значения параметра

Пример запроса

PUT /sso/api/settings/{principal}/event-notifier/default/enabled
Host: {sso_host}
Content-Type: application/json
Accept: application/json
Authorization: Bearer {access_token}

{value}

• {principal} - строковое поле с идентификатором пользователя. Для авторизованного пользователя допустимо использование @me

• {value} - значение true для включения опции или false для отключения

• {access_token} - токен доступа

В случае успешной установки параметра, будет возвращен пустой ответ с HTTP статусом 204.

В случае использования недопустимых параметров, будет возвращен ответ с HTTP статусом 400.

В случае ошибки авторизации, будет возвращен ответ с HTTP статусом 401.

Получение значения параметра

Пример запроса

GET /sso/api/settings/{principal}/event-notifier/default/enabled
Host: {sso_host}
Accept: application/json
Authorization: Bearer {access_token}

• {principal} - строковое поле с идентификатором пользователя. Для авторизованного пользователя допустимо использование @me

• {access_token} - токен доступа

В случае успешной установки параметра, будет возвращен ответ со значением запрошенного параметра в теле и HTTP статусом 200.

Пример ответа

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

true

В случае использования недопустимых параметров, будет возвращен ответ с HTTP статусом 400.

В случае ошибки авторизации, будет возвращен ответ с HTTP статусом 401.

Сброс параметра

Метод позволяет сбросить параметр на значение по умолчанию.

Пример запроса

DELETE /sso/api/settings/{principal}/event-notifier/default/enabled
Host: {sso_host}
Accept: application/json
Authorization: Bearer {access_token}

• {principal} - строковое поле с идентификатором пользователя. Для авторизованного пользователя допустимо использование @me

• {access_token} - токен доступа

В случае успешной установки параметра, будет возвращен пустой ответ с HTTP статусом 204.

Настройка транспортов для отправки уведомлений о событиях

Получение всех значений

Можно получить ассоциативный массив со всеми доступными категориями транспорта для конкретной категории события и их значеними.

Пример запроса

GET /sso/api/settings/{principal}/event-notifier/{category}/transports
Host: {sso_host}
Accept: application/json
Authorization: Bearer {access_token}

• {principal} - строковое поле с идентификатором пользователя. Для авторизованного пользователя допустимо использование @me

• {category} - категория события. Например, auth-success — событие успешной аутентификации.

• {access_token} - токен доступа

Пример ответа

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

{
  "push": true,
  "sms": true
}

В качестве ключа указывается категория транспорта, в качестве значения — её активность.

Получение значения категории транспорта для конкретной категории события

Пример запроса

GET /sso/api/settings/{principal}/event-notifier/{category}/transports/{transport}
Host: {sso_host}
Accept: application/json
Authorization: Bearer {access_token}

• {principal} - строковое поле с идентификатором пользователя. Для авторизованного пользователя допустимо использование @me

• {category} - категория события. Например, auth-success — событие успешной аутентификации.

• {transport} - категория транспорта. Например, sms.

• {access_token} - токен доступа

Пример ответа

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

true

Установка значения категории транспорта для конкретной категории события

Пример запроса

PUT /sso/api/settings/{principal}/event-notifier/{category}/transports/{transport}
Host: {sso_host}
Accept: application/json
Content-Type: application/json
Content-Length: 5
Authorization: Bearer {access_token}

false

• {principal} - строковое поле с идентификатором пользователя. Для авторизованного пользователя допустимо использование @me

• {category} - категория события. Например, auth-success — событие успешной аутентификации.

• {transport} - категория транспорта. Например, sms.

• {access_token} - токен доступа

Пример ответа

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

false

Категории транспорта

Идентификатор	Описание
sms	SMS
push	Push сообщения в мобильных устройствах