WebAPI — связь приложений с сайтом
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
API
AAPIMethod.php
Config.php
IAPIMethod.php
LICENSE-EN.txt
LICENSE-FULL-EN.txt
LICENSE-RU.txt
README.md
Request.php
Response.php
Token.php
User.php
WebAPI.php
WebAPIException.php
admin.php
functions.php
info.dat

README.md

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).

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