Skip to content

Home

Jump to bottom
Yuriy Gintsyak edited this page Mar 10, 2016 · 30 revisions

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

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

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

Статус API

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

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

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

HTTP API v1.xx

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

Method URI Status Page Link
GET /api/client/web/1.0/address/address experimental Поиск адреса
GET /api/client/web/1.0/address/point experimental Поиск адресной точки
GET /api/client/web/1.0/address/nearest experimental Поиск адреса по координатам
GET /api/client/web/1.0/tariff/options experimental Получение опций тарифа
POST /api/client/web/1.0/order/estimate experimental Предварительная оценка заказа
POST /api/client/web/1.0/order/submit experimental Заведение заказа
GET /api/client/web/1.0/order/confirm experimental Подтверждение заказа
GET /api/client/web/1.0/order/status experimental Получение статуса заказа

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.

Общие ошибки

Code Description
-10001 Отсутствует обязательный параметр
-10002 Неверный формат параметра запроса
-10003 Неверный формат JSON – документа в теле запроса

ErrorObj

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

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

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


{
    "code":-10001,
    "message": "missing required parameter 'my-very-valueable-parameter'"
}

Clone this wiki locally