Page tree

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

Skip to end of metadata
Go to start of metadata

Получение информации о Транспортных Средствах, доступных пользователю.

Запрос:

URL:

Запрос списка всех ТС пользователя:

GET https://api.url/v2.1/user/<user_id>/cars

Запрос ТС по id:

GET https://api.url/v2.1/user/<user_id>/cars/<car_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]int1000Количество ТС в выводе
fields[car]string

Фильтрация полей отображаемых в ТС.

прим:

Если в запросе задано fields[car]=Model,RegNumber

То ответ будет содержать только Model и RegNumber

filter[car]string

Фильтрация списка ТС.

Фильтрация поддерживается по всем полям, кроме CarState.

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

Позволяет добавить в текущий запрос связанные с ТС объекты.

Ответ:

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

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

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

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

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

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

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

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

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


metaСодержит total_count - количество тс у пользователя
data

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

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

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

Объекты с которыми связана ТС.


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

ПолеТипNullableОписание

InventoryNumber

stringда

Инвентарный номер ТС

BrandstringдаМарка ТС (deprecated)
Modelstringда

Модель ТС (своё название модели, используется если модели нет в справочнике)

RegNumberstringнетРегистрационный номер ТС

VIN

stringдаVIN номер

IsHidden

boolнетСкрывать ТС
DescriptionstringдаОписание
ReleaseDatedateдаДата выпуска ТС (когда тс была собрана)
DateOfCreationdatetimeда

Дата создания ТС

Связанные объекты:

ПолеТипNullableОписание

Owner

object<user>нетПользователь с которому принадлежит ТС

CarType

object<carType>нетТип ТС - см. v2.1 Типы ТС / Объектов

CarState

object<carState>даПоследнее известное состояние датчиков на ТС (если null то ТС ни разу не выходило на связь)

FuelType

object<fuelType>даТип топлива на ТС - v2.1 Типы топлива
OperatedZonelinkдаПривязанные к ТС зоны.
Deviceobject<device>даБортовое устройство

Коды ответов:

200 ОК - Сервер обработал запрос. В теле ответа  содержится список ТС. Также будет передан заголовок Last-Modified.

304 Not Modified - Сервер обработал запрос. Изменения не найдены.

401 Unauthorized - не передан заголовок Authorization, либо токен не корректный, либо окончился период действия.

403 Forbidden - нет прав на просмотр (id пользователя не соответствует токену).

404 Not Found - ТС не найдена или принадлежит другому пользователю.

400 Bad Request - Переданы не поддерживаемые параметры либо сервер не понял запрос (описание ошибки в теле ответа).

Также возможны другие ошибки.

Пример

Запрос списка всех ТС:

GET https://api.url/v2.1/user/1/cars 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": "http://api.url/v2.1/user/1/cars",
        "first": "http://api.url/v2.1/user/1/cars",
        "next": "https://api.url/v2.1/user/1/cars?page[offset]=200&page[limit]=200",
        "last": "https://api.url/v2.1/user/1/cars?page[offset]=400&page[limit]=200"
    },
   "meta":{
        "total_count": 450
    },
    "data": [
        { "type": "car",
          "id": "1",
          "attributes": {
              "InventoryNumber": "123",
              "Brand": null,
              "Model": null,
              "RegNumber": "k 123 at 111",
              "VIN": null,
              "IsHidden": 1,
              "Description": null,
              "ReleaseDate": "2014-01-01",
              "DateOfCreation": "2014-10-09T16:04:19Z"
          },
          "relationships":{
              "СarType": { 
                  "data": {"type": "carType", "id":"1"}
              },
              "СarState":{
                  "data": {"type": "carState", "id": "1"}
              },
			  "FuelType": {
                  "data": {"type": "fuelType","id": "1"}
              },
              "OperatedZones": {
                  "links": {"self": "http://api.url/v2.1/user/1/cars/1/relationships/OperatedZones"}
              },
              "Device": {
                 "data": null
              },
              "CarBrand": {
                 "data": null
              },
              "CarModel": {
                 "data": null
              }
          }
        },
        { "type": "car",
          "id": "2",
          "attributes": {
              "InventoryNumber": null,
              "Brand": "HandMade"
              "Model": "first",
              "RegNumber": "k 123 at 222",
              "VIN": "c312f22",
              "IsHidden": 0,
              "Description": "nice and shiny",
              "ReleaseDate": "2014-01-02",
              "DateOfCreation": "2014-10-10T16:04:19Z"
          },
          "relationships":{
              "СarType": { 
                  "data": {"type": "carType", "id": "101"}
              },
              "СarState":{
                  "data": {"type": "carState", "id": "2"}
              },
			  "FuelType": {
                  "data": {"type": "fuelType","id": "2"}
              },
              "OperatedZones": {
                  "links": {"self": "http://api.url/v2.1/user/1/cars/2/relationships/OperatedZones"}
              },
              "Device": {
                  "data": null
              },
              "CarBrand": {
                 "data": {"type": "carBrand", "id": 1}
              },
              "CarModel": {
                 "data": {"type": "carModel", "id": 1}
              }
          }
        }, 
         ... остальные тс ...

    ]
}


  • No labels