Astashov Andrey edited this page Jan 11, 2018 · 29 revisions

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

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

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

Статус API

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

  • experimental – Экспериментальный. Еще не достаточно хорошо протестированы, велика вероятность каких-либо изменений в форматах запросов/ответов, также возможно изъятие функции из API;
  • candidatAPI протестирован командой разработки, возможны мелкие изменения в форматах запросов (с большой вероятностью без потери обратной совместимости при переходе от experimental к unstable);
  • stableAPI зафиксирован. Изменения могут быть внесены только при условии сохранения обратной совместимости. Если сохранение обратной совместимости невозможно, будет разработана новая версия интерфейсного вызова.
  • 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) не существует
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.