''[[span(style=color: #FF0000, Статья находится в стадии создания! )]]''

= __MC04-DSL-3U API__ =

== Общие положения ==

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 и ответы на них представляют собой [https://ru.wikipedia.org/wiki/JSON 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-сообщения двумя способами:
1. как значение параметра `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
}}}
1. как "чистый" 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 к первому варианту запросов.