Получение списка команд которые поддерживаются на данной ТС.
Запрос:
URL:
Список команд по всем ТС (команда отображается если доступна хотя бы на 1 из тс):
GET https://api.url/v2.1/user/<user_id>/cars/commands/allowed
Полный список команд на ТС:
GET https://api.url/v2.1/user/<user_id>/cars/<car_id>/commands/allowed
Описание отдельной команды (проверка что команда поддерживается):
GET https://api.url/v2.1/user/<user_id>/cars/<car_id>/commands/allowed/<command_desc_id>
Доп. Заголовки:
If-Modified-Since - Если ранее уже запрашивался полный список ТС, то при обновлении следует указывать заголовок If-Modified-Since с датой полученной заголовка ответа Last-Modified
Accept - для указания формата ответа. Должен быть "application/vnd.api+json", для совместимости принимается также "application/json".
Authorization - для передачи токена. Передается в формате: Bearer <access_token>.
Доп. Параметры запроса:
| Поле | Тип | Значение по умолчанию | Описание |
|---|---|---|---|
| page[offset] | int | 0 | Пропустить несколько первых записей |
| page[limit] | int | 2000 | Количество комманд в выводе |
| fields[commandDescripion] | string | Фильтрация полей в описании команды. | |
| filter[commandDescripion] | string | Фильтрация списка команд. | |
| sort | string | Сортировка по указанному полю |
Параметр include (определённый в стандарте JSON API) в текущей версии api не поддерживается. В случае их получения сервер будет возвращать ошибку 400.
Ответ:
Ответ присылается в формате JSON API.
| Поле | Описание | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| links | Поле links содержит ссылки на доступные ресурсы. Минимально он должен содержать ссылку на текущий ресурс (self). Если Все команды не удалось поместить в одном ответе то также будет содержаться next - следующая страница (если есть) prev - предыдущая страница (если есть) first - первая страница с результатами last - последняя страница с результатами | ||||||||||||
| meta | Содержит total_count - количество доступных команд. | ||||||||||||
| data | Содержит массив объектов command в формате JSON API. Каждый объект содержит:
|
Список атрибутов команды:
| Поле | Тип | Null | Описание |
|---|---|---|---|
| Name | text | нет | Название команды |
| Description | text | да | Описание команды |
| Parameters | object | нет | Параметры команды (не поддерживается в filter и sort) |
ParametersValues | object | да | Установленные параметры команды |
Список связанных объектов:
| Поле | Тип | Null | Описание |
|---|---|---|---|
| Creator | object<user> | да | Кто создал команду Не null только для команд созданных пользователями. |
| ParentCommandId | object<commandDescripion> | да | Из какой команды создана данная |
Описание параметров:
| Name | Название параметра |
| Description | Описание параметра |
| Type | int, decimal, date, datetime, enum |
| other fields ... | Остальные параметры зависят от типа. |
Описание параметров:
| Название поля | Описание |
|---|---|
| Name | Название параметра |
| Description | Описание параметра |
| Type | int, decimal, date, datetime, enum |
| other fields ... | Остальные параметры зависят от типа. |
Дополнительные поля параметров:
Для всех параметров required по умолчанию true.
Все доп поля являются необязательными, кроме тех где явно указано обратное.
Поле параметра - default должно использоваться клиентским приложением как значение по умолчанию. При создании команды, если данное поле не передано, API не будет подставлять в него default, это поле будет считаться отсутствующим / не определённым.
Int:
ranges: [{min, max}] где min и max - объект {value: int, inclusive: bool}, в объекте должно быть определено хотя бы либо min либо max, если определено только min то зачит что допустимы все значения выше min, аналогично для max,
required: bool,
default: int | null
Decimal;
ranges: аналогично ranges в int
required: bool,
default: decimal | null
Date:
ranges: аналогично ranges в int,
required: bool,
default: date | null
DateTime:
ranges,
required: bool,
default: datetime | null
String:
min: int,
max: int,
regexp: string,
required: bool,
default: string | null
Enum:
options: [{name: string, value: string|decimal|null, is_default: bool}], (обязательное поле)
required: bool
Пример:
GET https://api.url/v2.1/user/1/cars/1/commands/allowed HTTP/1.1
Accept: application/vnd.api+json
Authorization: Bearer <auth token>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
Allow: GET
Last-Modified: Wed, 21 Oct 2015 07:28:00 GMT
{
"links": {
"self": "https://api.url/v2.1/user/1/cars/1/commands/allowed"
},
"meta": {
"total_count": 3
},
"data": [
{
"id": "1",
"type": "сommandDescription",
"attributes": {
"Name": "Turn engine ON",
"Description": "Turn on engine in car",
"Parameters": [],
"ParametersValues": null
},
"relationships": {
"Creator": {
"data": null
},
"ParentCommandId": {
"data": null
}
}
},
{
"id": "2",
"type": "сommandDescription",
"attributes": {
"Name": "Scatter spikes",
"Description": "Scatter spikes to stop car behind you",
"Parameters": [
{
"name": "Amount of spikes",
"type": "int",
"required": false,
"default": 12,
"ranges": [
{ "min": {"value": 12, "inclusive": true},
"max": {"value": 100, "inclusive": true} }
]
}
],
"ParametersValues": null
},
"relationships": {
"Creator": {
"data": null
},
"ParentCommandId": {
"data": null
}
}
},
{
"id": "3",
"type": "сommandDescription",
"attributes": {
"Name": "Wake up all neighbors",
"Description": "Turn Alarm ON",
"Parameters": [
{
"name": "Duration",
"description": "how long alarm should be turned on, in seconds",
"type": "int"
}
],
"ParametersValues": null
},
"relationships": {
"Creator": {
"data": null
},
"ParentCommandId": {
"data": null
}
}
}
]
}