API аппаратуры MC04-DSL-3U
Общие положения
API аппаратуры MC04-DSL-3U используется для получения состояния аппаратуры и управления ее работой через сеть передачи данных. Одним из примеров использования API является управление аппаратурой веб-браузером посредством встроенного в аппаратуру веб-интерфейса.
API построен на клиент-серверной архитектуре и использует встроенный в аппаратуру MC04-DSL-3U HTTP (HTTPS) сервер. Любое взаимодействие с ааппаратурой посредством API представляет собой последовательность "запрос-ответ": клиент передает серверу запрос, на который получает от сервера ответ.
Протокол
Для передачи запросов API и получения ответов может использоваться как HTTP, так и HTTPS протокол. Рекомендуется использовать протокол HTTPS как более защищенный и безопасный, однако следует учитывать, что для работы этого протокола аппаратуре MC04-DSL-3U требуется дополнительная настройка (установка сертификатов), и если такую настройку не произвести, протокол HTTPS окажется недоступен.
Для передачи запроса используется URI вида http[s]://<host>/api.php
, например:
https://mc04.domain.org/api.php
.
Примечание: в аппаратуре ранних версий в URI для некоторых запросов должен был использоваться путь отличный от /api.php. Такие случаи оговариваются в описаниях конкретных запросов.
Для отправки запроса серверу могут использоваться методы GET и POST. Предпочтительным является использование метода POST.
Кодировка (набор символов)
Текстовые строки, передаваемые в запросах и ответах API кодируются в UTF-8.
Структура данных
Все запросы API и ответы на них представляют собой JSON-объекты. Данные запросов и ответов в таком объекте имеют следующий вид:
{"key1":value,"key2":value...}
При использовании метода GET JSON-объект передается серверу как значение параметра json
(которое должно быть закодировано по правилам urlencode), например:
GET api.php?json=%7B%22key%22%3A123%2C%22key2%22%3A%22labuda%22%7D HTTP/1.1 Host: mc04.domain.org
При использовании метода POST запрос может помещаться в тело HTTP-сообщения двумя способами:
- как значение параметра
json
(аналогично запросу GET), в этом случае поле Content-Type сообщения должно иметь значениеapplication/x-www-form-urlencoded
, и, соответственно, тело сообщения должно кодироваться по правилам urlencode. Пример запроса:POST /api.php HTTP/1.1 Host: mc04.domain.org Content-Type: application/x-www-form-urlencoded Content-Length: xxx json=%7B%22key%22%3A%22value%22%7D
- как "чистый" json-объект, в этом случае никакого дополнительного кодирования не используется, поле Content-Type в этом случае должно иметь значение
application/json
. Пример запроса:POST /api.php HTTP/1.1 Host: mc04.domain.org Content-Type: application/json Content-Length: xxx {"key":"value"}
Предпочтительным является второй вариант, однако следует учитывать, что его поддержка появилась в аппаратуре MC04-DSL-3U лишь начиная с ревизии пакета sw r1543, в более ранних ревизиях поддерживается только первый вариант, поэтому для поддержки более ранних версий аппаратуры при разработке клиента рекомендуется предусмотреть возможность fallback к первому варианту запросов.
Обязательным ключом JSON-объекта является cmd
, значением которого является строка - имя команды, выполнение которой запрашивает клиент (в случае запроса) или результат выполнения которой передает клиенту сервер (в случае ответа).
При возникновении ошибки в процессе выполнения команды сервер возвращает ответ на команду, в котором присутствует ключ error
. Значением ключа является строка с описанием возникшей ошибки. Признаком успешного выполнения команды является отсутствие в ответе на нее ключа error
.
JSON-объект может также содержать другие ключи, их состав и назначение определяется выполняемой командой и описаны в разделе каждой команды.
Аутентификация
Для выполнения большинства команд требуется аутентификация. Для выполнения аутентификации требуется выполнить команду login. При успешной аутентификации ответ сервера устанавливает cookies с данными аутентификации. Эти cookies должны присутствовать в последующих командах. Установленные данные аутентификации действительны в течение суток с момента их генерации.
В случае, если при передаче запроса к серверу cookies с данными аутентификации отсутствуют, неверны или устарели (сгенерированы более суток назад), команда сервером не выполняется, и в ответе присутствует ключ error
со значением "not logged in". При получении этой ошибки необходимо повторно выполнить аутентификацию.
При наличии в запросе cookies с валидными данными аутентификации в ответе на любую команду сервер может установить новые (обновленные) cookies. Как правило, при периодическом обращении к серверу это происходит каждые 10 секунд. Таким образом, необходимость в повторном выполнении команды login возникает только если в течение суток серверу не передавалось ни одного запроса.
Права доступа
Некоторые команды для их выполнения требуют наличия у пользователя, запросившего их выполнения, определенных прав доступа. Например команда reboot
требует наличия у пользователя права изменения текущей конфигурации, в команда saveall
требует наличия права сохранения конфигурации в ПЗУ.
В случае, если у пользователя, запросившего выполнение команды отсутствует хотя бы одно из необходимых для ее выполнения прав, команда не выполняется, а запросившему ее клиенту возвращается ответ, содержащий ошибку "access denied". Пример такого ответа:
{"cmd":"saveall","error":"access denied"}