| 1 | ''[[span(style=color: #FF0000, Статья находится в стадии создания! )]]'' |
| 2 | |
| 3 | = __MC04-DSL-3U API__ = |
| 4 | |
| 5 | == Общие положения == |
| 6 | |
| 7 | API аппаратуры MC04-DSL-3U используется для получения состояния аппаратуры и управления ее работой через сеть передачи данных. Одним из примеров использования API является управление аппаратурой веб-браузером посредством встроенного в аппаратуру веб-интерфейса. |
| 8 | |
| 9 | API построен на клиент-серверной архитектуре и использует встроенный в аппаратуру MC04-DSL-3U HTTP (HTTPS) сервер. Любое взаимодействие с ааппаратурой посредством API представляет собой последовательность "запрос-ответ": клиент передает серверу запрос, на который получает от сервера ответ. |
| 10 | |
| 11 | == Протокол == |
| 12 | |
| 13 | Для передачи запросов API и получения ответов может использоваться как HTTP, так и HTTPS протокол. Рекомендуется использовать протокол HTTPS как более защищенный и безопасный, однако следует учитывать, что для работы этого протокола аппаратуре MC04-DSL-3U требуется дополнительная настройка (установка сертификатов), и если такую настройку не произвести, протокол HTTPS окажется недоступен. |
| 14 | |
| 15 | Для передачи запроса используется URI вида `http[s]://<host>/api.php`, например: |
| 16 | |
| 17 | `https://mc04.domain.org/api.php`. |
| 18 | |
| 19 | ''Примечание: в аппаратуре ранних версий в URI для некоторых запросов должен был использоваться путь отличный от /api.php. Такие случаи оговариваются в описаниях конкретных запросов.'' |
| 20 | |
| 21 | Для отправки запроса серверу могут использоваться методы GET и POST. Предпочтительным является использование метода POST. |
| 22 | |
| 23 | == Структура данных == |
| 24 | |
| 25 | Все запросы API и ответы на них представляют собой [https://ru.wikipedia.org/wiki/JSON JSON]-объекты. Данные запросов и ответов в таком объекте имеют следующий вид: |
| 26 | |
| 27 | `{"key1":value,"key2":value...}` |
| 28 | |
| 29 | При использовании метода GET JSON-объект передается серверу как значение параметра `json`, например: |
| 30 | |
| 31 | `https://mc04.domain.org/api.php?json={"key":123,"key2":"labuda"}` |
| 32 | |
| 33 | При использовании метода POST |