Changes between Version 2 and Version 3 of Api

Timestamp:

Aug 12, 2017, 9:02:24 PM (8 years ago)

Author:

alx

Comment:

Дописан раздел "Структура данных", добавлены "Аутентификация" и "Права доступа".

Api

@@ -60 +60 @@
 
 Предпочтительным является второй вариант, однако следует учитывать, что его поддержка появилась в аппаратуре 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"}`