Permalink
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
134 lines (94 sloc) 8.22 KB

WebAPI — связь приложений с сайтом

Текущая версия: 1.0

Дополнение, позволяющее внешним одобренным сервисам и приложениям взаимодействовать с сайтом, работающим под управлением Ruxe Engine.

Одним из таких приложений является Ruxe Engine Monitor на Android.

Обсуждение на форуме: https://ruxe-engine.ru/forum/viewtopic.php?f=21&t=179&p=2399

  1. Установка

Распаковать содержимое в каталог /includes/plugins/ вашего сайта. Требуется PHP 5.4+ и Ruxe Engine 1.8+.

  1. Регламент методов API

  • Запрос осуществляется по адресу:

    http://сайт/?action=webapi&request=ИМЯ_МЕТОДА_API
    
  • Данные, передаваемые с запросом на сервер, отправляются либо как POST, либо как PUT, UPDATE или DELETE в JSON формате. В GET данные не передавать!

  • Метод API - есть класс в каталоге /includes/plugins/webapi/API/, реализующий интерфейс RuxeEngine\Plugins\WebAPI\IAPIMethod;

  • Для удобства можно наследоваться от абстрактного класса RuxeEngine\Plugins\WebAPI\AAPIMethod;

  • Ответ, возвращаемый методом API, должен быть в формате JSON, иметь заголовок:

    Content-Type: application/json; charset=UTF-8
    

    и содержать как минимум один ключ - "status" со значением "good" либо "bad". В случае статуса "bad" должен быть ключ "reason" с строковым значением причины ошибки, выводимой пользователю. Для удобства рекомендуется использовать RuxeEngine\Plugins\WebAPI\Response, имеющий методы для отправки данных клиенту в нужном формате;

  • Генерируемые исключения, которые следует отлавливать в родительских классах, наследуются от RuxeEngine\Plugins\WebAPI\WebAPIException;

  • Имя метода API (то бишь класса в /includes/plugins/webapi/API/) может содержать только латинские буквы;

  • Т.к. в Ruxe Engine 1 нет автозагрузчика, файлы с классами методов API придётся подключать вручную в functions.php в соответствующем участке кода:

    ...
    // ДЛЯ РАЗРАБОТЧИКОВ: API методы. Т.к. в Ruxe Engine 1 нет автозагрузчика,
    // используемые файлы классов нужно подключать самому здесь:
    require_once __DIR__ . "/API/GetAdminNotifications.php";
    require_once __DIR__ . "/API/GetVersion.php";
    require_once __DIR__ . "/API/GetNewToken.php";
  1. Авторизация

Для того, чтобы проверить подлинность приложения, работающего с WebAPI, используется токен. Токен передаётся в POST с ключом "token" в запросах к API. Чтобы получить токен, необходимо отправить на:

http://сайт/?action=webapi&request=GetNewToken

POST данные: login, password и secret с секретной случайной комбинацией букв и цифр для надёжности токена. Будет сгенерирован и сохранён новый токен, который в последующем будет ожидаться в других методах API.

  1. Как проверить токен из метода API

Например, так:

if (! isset($_POST["token"])) {
    Response::sendError("Некорректный запрос: отсутствует token.");
}

$token = new Token($this->config, $_POST["token"]);
if (! $token->isCorrect()) {
    Response::sendError("Token не задан или не верен.");
}
  1. Методы API, включённые в плагин

GetAdminNotifications

Ожидает POST "token". Возвращает JSON результат с новыми сообщениями из админ-центра вида

{
    "status": "good",
    "notifications": [
        {
            "title": string,
            "warning": bool,
            "content": string
        },
        ...
    ]
}

GetVersion

Ожидает POST "token". Возвращает версию установленного на сайте Ruxe Engine в JSON формате вида:

{
    "status": "good",
    "version": string
}

GetNewToken

Ожидает POST "login", "password" и "secret" с секретной случайной комбинацией букв и цифр. Генерирует новый токен, сохраняет его и возвращает JSON результат вида:

{
    "status": "good",
    "token": string
}
  1. Безопасность

Как выглядит "токен" и безопасен ли он? Токен - это md5 хэш:

return md5( md5(rand(0, time())) . "{$salt}{$salt}{$secret}{$secret}" );

Расшифровать его нельзя. Кто-то может предположить, что зная как он формируется (исходники плагина WebAPI ведь открыты и вот выше код представлен), его возможно подобрать на CUDA процессорах в течении месяца другого, а подобрав - разузнать соль пользователя. Можно подумать, что если имеется откуда-то хэш пароля администратора, то с помощью соли возможно подобрать пароль ещё спустя месяцы (как формируется хэш пароля администратора можно узнать из открытых исходников Ruxe Engine ведь). Но хрен! :) Даже если по какой-то причине у злоумышленника есть токен и хэш пароля администратора, из токена он не сможет узнать соль, потому что ему мешает рандом (пусть это и псевдослучайные числа), а также "$secret", который вводит пользователь в приложении - эта комбинация случайных букв нигде не сохраняется и служит абсолютным рандомом, полностью ликвидируя возможность узнать соль из подобранного хэша.

Токен сохраняется в /conf/webapi.json сайта и в приложении - при тождественном совпадении (===), авторизация одобряется.

  1. Автор и лицензия

Ахрамеев Денис Викторович (http://ahrameev.ru) - Автор, программирование

Это произведение доступно по Open Source лицензии Creative Commons «Attribution-ShareAlike» («Атрибуция — На тех же условиях») 4.0 Всемирная (CC BY-SA 4.0).

Краткий текст лицензионного соглашения: на русском, на английском.