API

Все настройки SHM и всё управление системой осуществляется с помощью вызовов API.

Web интерфейс администратора и кабинет клиента работают на основе API.

HTTP Методы

SHM API использует стандартные методы протокола HTTP:

SHM API v1 отвечает в следующем формате:

{
    data: [
        {
            item: 1
        },
        {
            item: 2
        }
    ],
    items: 2
}

HTTP коды ответов

При работе с SHM API рекомендуется проверять коды ответов HTTP.

200 - УСПЕХ для GET, POST, PUT запросов

201 - УСПЕХ для DELETE запросов (эти запросы не возвращают ответа в теле)

400 - ошибка запроса, неверные или недостающие аргументы

403 - не авторизован, требуется авторизация

404 - объект не найден

5xx - ошибки сервера

Аутентификация

Аутентификация через Cookies (session_id)

Получаем session_id:

curl -H "Content-Type: application/json" \
     -X POST http://$SERVER/shm/user/auth.cgi \
     -d '{"login": "admin", "password": "admin"}'

пример ответа:

{ "session_id": "3f928c835ff78f836c4066c112b292c5" }

Запрос с использованием cookies (session_id):

curl --cookie "session_id=3f928c835ff78f836c4066c112b292c5" http://$SERVER/shm/v1/user

Basic-аутентификация

curl -u "admin:admin" http://$SERVER/shm/v1/user

Bearer-аутентификация (API-токен)

Для интеграций и внешних сервисов удобнее не использовать логин/пароль пользователя, а выпустить отдельный аккаунт-токен (type: "token"). Токен генерируется на сервере и показывается в открытом виде только один раз - в ответе на создание. Дальше хранится только его sha256-хеш, поэтому восстановить или посмотреть токен повторно нельзя - при утере нужно создать новый.

Создание токена (доступно только администратору):

curl -u "admin:admin" -X PUT \
     -H "Content-Type: application/json" \
     -d '{"user_id": 42, "type": "token"}' \
     http://$SERVER/shm/v1/admin/user/accounts

пример ответа:

{
    "data": [
        {
            "login": "kQ7s...64-символьный токен...9zP2",
            "type": "token",
            "user_id": 42,
            "settings": {}
        }
    ]
}

Значение login из ответа и есть сам токен - сохраните его, повторно он не выдаётся.

Запрос с использованием токена:

curl -H "Authorization: Bearer kQ7s...64-символьный токен...9zP2" http://$SERVER/shm/v1/user

При создании токена можно указать gid в settings - тогда доступ по токену будет ограничен, как у пользователя соответствующей группы администраторов:

curl -u "admin:admin" -X PUT \
     -H "Content-Type: application/json" \
     -d '{"user_id": 42, "type": "token", "settings": {"gid": 2}}' \
     http://$SERVER/shm/v1/admin/user/accounts

Аутентификация через header-ы

curl -H "session-id: 3f928c835ff78f836c4066c112b292c5" http://$SERVER/shm/v1/user

curl -H "login: admin" -H "password: admin" http://$SERVER/shm/v1/user

Аутентификация через Query string

curl http://$SERVER/shm/v1/user?session_id=3f928c835ff78f836c4066c112b292c5

Список ресурсов