Работа с API-запросами
API (Application Programming Interface) — это набор правил и инструментов для взаимодействия программ друг с другом. В PILOT API используется для обмена данными между системами, сервисами, приложениями и платформой.
API-запрос состоит из:
-
URL — адрес API-сервера и команда
-
Параметры запроса — данные, которые передаются на сервер
-
Метод запроса — способ взаимодействия с сервером
Как работает API в PILOT
PILOT использует распределённую инфраструктуру, которая включает несколько серверов, например, BLADE, KSA, AFRICA, USA. У каждого сервера может быть несколько узлов — нод, со своим номером.
Когда вы отправляете API-запроса к системе, вы можете указать конкретный сервер (например, BLADE), а также конкретный узел внутри этого сервера — node. Так, запрос будет обработан напрямую на выбранном сервере и конкретном узле без лишних пересылок и с минимальным временем отклика.
Пример запроса
https://blade.pilot-gps.com/api/api.php?cmd=list&node=14
|
blade.pilot-gps.com — это имя сервера
node=14 — указание на узел (сервер), где должен быть обработан запрос.
Методы запросов в API
GET
Метод для получения данных. Используется, например, для запроса списка объектов или информации об аккаунте.
В GET-запросе команда и параметры передаются прямо в URL. Параметры добавляются после знака ? и разделяются символом &.
Пример
https://<address>/api/api.php?cmd=bindControl&uid=123&imei=456&lineuid=789
|
cmd=bindControl — команда
uid=123, imei=456, lineuid=789 — параметры
POST
Метод для отправки данных. Например, используется для создания нового объекта или формирования отчёта.
В POST-запросе команда и параметры могут передаваться в теле запроса или команда указывается в URL, а параметры передаются в теле.
Пример 1
URL: https://<address>/api/api.php?cmd=bindControl
Тело запроса
{
"uid": "123",
"imei": "456",
"lineuid": "789"
}
|
Пример 2
URL: https://<address>/api/api.php
Тело запроса
{
"cmd": "bindControl",
"uid": "123",
"imei": "456",
"lineuid": "789"
}
|
PUT
Метод для обновления данных. Этот вид запроса используется, например, для изменения параметров объекта или аккаунта.
Чаще всего PUT используется для обновления конкретного ресурса, поэтому идентификатор обычно указывается в URL, а обновляемые данные — в теле.
Пример
URL: https://<address>/api/api.php/123
Тело запроса:
{
"cmd": "updateControl",
"uid": "123",
"imei": "456",
"lineuid": "789",
"status": "active"
}
|
DELETE
Метод для удаления данных. Например, если нужно удалить объект или аккаунт, используется этот метод.
В DELETE-запросе команда и параметры обычно передаются в URL.
Пример
https://<address>/api/api.php?cmd=bindControl&uid=123&imei=456&lineuid=789
|
Формат данных
API поддерживает различные форматы как для запросов, так и для ответов.
JSON:
{
"cmd": "bindControl",
"uid": "123",
"imei": "456",
"lineuid": "789"
}
|
Form-encoded:
cmd=bindControl&uid=123&imei=456&lineuid=789
|
XML:
<request>
<cmd>bindControl</cmd>
<uid>123</uid>
<imei>456</imei>
<lineuid>789</lineuid>
</request>
|
Типы данных
В API используются различные типы данных для передачи информации между клиентом и сервером. Рассмотрим основные типы данных, которые могут встречаться в запросах и ответах API.
|
Тип данных
|
Описание
|
Пример в json-формате
|
Для чего используются
|
|
Строка (String)
|
Текст в кавычках
|
"name": "Маршрут №9"
|
Для текстовых данных: названия, описания
идентификаторы
|
|
Число (Number)
|
Числовое значение, целое или дробное
|
"price": 15.35
|
Для числовых данных: цены
идентификаторы, координаты, время
|
|
Массив (Array)
|
Упорядоченный список элементов любого типа
|
"points": [{"lat": "53.352142", "lon": "83.758749"}, {"lat": "52.534012", "lon": "85.178777"}]
|
Для списков данных: остановки, товары,
пользователи
|
|
Объект (Object)
|
Набор пар "ключ — значение"
|
"uid": "1", "lat": "53.352142", "lon":"83.758749"}
|
Для структурированных данных:
информация об остановке, пользователе, заказе
|
|
Булевый тип
(Boolean)
|
Логическое значение true/false или 1/0
|
"bidirectional": 1
|
Для флагов или состояний:
активен/неактивен, доступен/ недоступен
|