Changes between Version 1 and Version 2 of Api

Timestamp:

Aug 11, 2017, 10:04:29 PM (8 years ago)

Author:

alx

Comment:

Описаны форматы запросов POST.

Api

@@ -21 +21 @@
 Для отправки запроса серверу могут использоваться методы GET и POST. Предпочтительным является использование метода POST.
 
+== Кодировка (набор символов) ==
+
+Текстовые строки, передаваемые в запросах и ответах API кодируются в UTF-8.
+
 == Структура данных ==
 
@@ -27 +31 @@
  `{"key1":value,"key2":value...}`
 
-При использовании метода GET JSON-объект передается серверу как значение параметра `json`, например:
+При использовании метода GET JSON-объект передается серверу как значение параметра `json` (которое должно быть закодировано по правилам urlencode), например:
 
- `https://mc04.domain.org/api.php?json={"key":123,"key2":"labuda"}`
+{{{
+GET api.php?json=%7B%22key%22%3A123%2C%22key2%22%3A%22labuda%22%7D HTTP/1.1
+Host: mc04.domain.org
 
-При использовании метода POST 
+}}}
+
+При использовании метода 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 к первому варианту запросов.