Page tree

Citypoint - контроль и аналитика автопарка

Skip to end of metadata
Go to start of metadata

Получение списка команд которые поддерживаются на данной ТС.

Запрос:

URL:

Полный список команд на ТС:

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]int0Пропустить несколько первых записей
page[limit]int2000Количество комманд в выводе
fields[CommandDescripion]string

Фильтрация полей в описании команды.

filter[CommandDescripion]string

Фильтрация списка команд.

sortstring
Сортировка по указанному полю

Параметр include (определённый в стандарте JSON API) в текущей версии api не поддерживается. В случае их получения сервер будет возвращать ошибку 400.

Ответ:

       Ответ присылается в формате JSON API.

ПолеОписание
links

Поле links содержит ссылки на доступные ресурсы.

Минимально он должен содержать ссылку на текущий ресурс (self).

Если Все команды не удалось поместить в одном ответе то также будет содержаться

next - следующая страница (если есть)

prev - предыдущая страница (если есть)

first - первая страница с результатами

last - последняя страница с результатами


metaСодержит total_count - количество доступных команд.
data

Содержит массив объектов command в формате JSON API.

Каждый объект содержит:

ПолеТипОписание
idintИдентификатор команды (передаётся строкой)
typestringТип ресурса (всегда "commandDescripion")
attributesobjectДанные объекта (см. Описание атрибутов commandDescripion)

Список атрибутов команды:

ПолеТипNullОписание
NametextнетНазвание команды
DescriptiontextдаОписание команды
ParametersobjectнетПараметры команды (не поддерживается в filter и sort)

ParametersValues

objectдаУстановленные параметры команды

Список связанных объектов:

ПолеТипNullОписание
Creatorobject<user>да

Кто создал команду

Не null только для команд созданных пользователями.

ParentCommandIdobject<commandDescripion>даИз какой команды создана данная

Описание параметров:

Name

Название параметра

DescriptionОписание параметра
Typeint, decimal, date, datetime, enum
other fields ...Остальные параметры зависят от типа.

Описание параметров:

Название поляОписание
Name

Название параметра

DescriptionОписание параметра
Typeint, 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
                }
            }
        }
    ]
}
  • No labels