API для клиентского виджета

API и клиентский виджет все еще находятся в разработке. Пожалуйста, будьте готовы к небольшим изменениям.

Документация также претерпевает изменения. Следите за обновлениями.

Статус API

Система активно разрабатывается как и API, которые она предоставляет. Для каждого элемента API определен его статус, определяющий степень его стабильности/готовности для использования:

• experimental – Экспериментальный. Еще не достаточно хорошо протестированы, велика вероятность каких-либо изменений в форматах запросов/ответов, также возможно изъятие функции из API;
• candidat – API протестирован командой разработки, возможны мелкие изменения в форматах запросов (с большой вероятностью без потери обратной совместимости при переходе от experimental к unstable);
• stable – API зафиксирован. Изменения могут быть внесены только при условии сохранения обратной совместимости. Если сохранение обратной совместимости невозможно, будет разработана новая версия интерфейсного вызова.
• deprecated – Кандидат на удаление из API. Использование deprecated частей API крайне не рекомендуется.

API в рамках одной major версии может быть только расширен (расширение интерфейса старых запросов, добавление новых)

HTTP API v1.xx

В этой секции приведен текущий статус API версии v1.xx.

Method	URI	Status	Page Link	Since
GET	/api/client/mobile/1.0/context	stable	link	1.19
GET	/api/client/web/1.0/address/address	stable	link	1.19
GET	/api/client/web/1.0/address/point	stable	link	1.19
GET	/api/client/web/1.0/address/nearest	stable	link	1.19
GET	/api/client/web/1.0/tariff/options	deprecated	link	1.19
POST	/api/client/web/1.0/order/estimate	stable	link	1.19
POST	/api/client/web/1.1/order/submit	stable	link	1.19
GET	/api/client/web/1.0/order/confirm	stable	link	1.19
GET	/api/client/web/1.0/order/status	stable	link	1.19
GET	/api/client/web/1.0/order/info	stable	link	1.19
GET	/api/client/web/1.0/order/cancel	stable	link	1.19

На страницах с детальным описанием запросов могут присутствовать дополнительные замечания по доступности функционала в зависимости от версии системы

HTTP headers

Во всех HTTP запросах к API должны быть представлены следующие заголовки:

Name	Type	Description
Hive-Context	number	Идентификатор контекста, определяющий службу такси, тариф, региональные настройки в рамках которых будут приниматься заказы. Один сервер может предоставлять несколько таких контекстов одновременно.

Если по каким-либо причинам хотя бы один из обязательных заголовков представлен не будет, сервер вернет код ответа – 400.

Система также распознает следующие необязательные HTTP заголовки:

Name	Type	Description
Accept-Language	string	Нужен для формирования локализованных текстов сообщений для отображения на странице с виджетом. Значение локали должно соответсвовать стандарту RFC 2616. Если это значение не указано – будут использоваться текущие региональные настройки сервера

Ответ от сервера

Возможные варианты ответа от сервера:

HTTP-Code	Response Body
200	Тело ответа будет содержать JSON Array или JSON Object в соответствии со спецификацией запроса
400	Тело ответа будет содержать JSON документ типа ErrorObj содержащий код ошибки и локализованное сообщение с описанием причины
404	Тело ответа будет пустым
500	Тело ответа будет пустым

Если запрос был успешно выполнен, ответ вернется с кодом 200.

Ошибки

ErrorObj

Общий формат объекта для передачи сообщений об ошибках

Name	Type	Required	Description
code	number	true	Код ошибки
message	string	true	Локализованное описание ошибки

Пример ответа с описанием ошибки:

{
    "code": -10003,
    "message": "Missing parameter: my-very-valueable-parameter." }

Коды ошибок

Общие коды ошибок

Code	Description
-10001	Отсутствует обязательный заголовок
-10002	Неверный формат заголовка
-10003	Отсутствует обязательный параметр запроса
-10004	Неверный формат параметра запроса
-10005	Неверный формат JSON-документа в теле запроса
-10006	Переданный идентификатор контекста (заголовок Hive-Context) не существует