GET - Список локаций

Эндпоинт GET /locations предназначен для получения списка доступных локаций. Локации представляют собой конкретные места, которые могут включать дополнительные данные, такие как графические планы, теги или другие атрибуты. Этот эндпоинт поддерживает фильтрацию, сортировку и поиск, чтобы помочь пользователям быстро и легко найти нужные локации.

Параметры запроса

Параметр	Описание	Тип	Обязательный	Значение по умолчанию
`limit`	Максимальное количество возвращаемых элементов.	Целое число	Нет	2147483647
`offset`	Количество элементов, которые следует пропустить в начале.	Целое число	Нет	0
`sort`	Критерии сортировки (например, `id,asc`).	Строка	Нет	`id,asc`
`q`	Быстрый поиск по текстовым полям.	Строка	Нет	-
`name`	Фильтрация по имени локации.	Строка	Нет	-
`address`	Фильтрация по адресу локации.	Строка	Нет	-
`withGraphicPlan`	Фильтрация по наличию графического плана.	Логическое	Нет	-
`tags`	Фильтрация по тегам, связанным с локацией.	Строка	Нет	-

Пример запроса

Чтобы получить список локаций, в имени которых содержится "Walmart", которые имеют графический план, и ограничить результат первыми 20 элементами:

GET /locations?limit=20&offset=0&sort=id,asc&q=Walmart&withGraphicPlan=true

Пример успешного ответа

Код состояния: 200 OK
Тип медиаданных: application/json

Тело ответа:

{
  "data": [
    {
      "id": "638b90c5-7965-49ae-a02b-1b190cb216db",
      "name": "W001",
      "address": "Walmart 11,197",
      "latitude": 51.0966229,
      "longitude": -138.491986,
      "tags": [
        "tag1"
      ],
      "graphicPlanIds": [
        "3a1da1c9-0873-4bdc-b1f1-7343b29fdc27",
        "14b8ec6b-8ee2-4533-aedd-b82691f19af2"
      ]
    }
  ],
  "meta": {
    "offset": 0,
    "limit": 20,
    "count": 1000,
    "sort": [
      {
        "property": "id",
        "direction": "asc"
      }
    ],
    "filter": [
      {
        "property": "name",
        "value": "W001"
      }
    ]
  }
}

Разбор ответа:

data: Содержит список локаций. Каждая локация включает:
- id: Уникальный идентификатор локации.
- name: Имя локации (например, "W001").
- address: Адрес локации (например, "Walmart 11,197").
- latitude: Широта локации.
- longitude: Долгота локации.
- tags: Теги, связанные с локацией (например, "tag1").
- graphicPlanIds: Список идентификаторов графических планов, связанных с локацией.
meta: Содержит метаданные о запросе:
- offset: Точка начала списка (то есть сколько элементов пропустить).
- limit: Количество запрашиваемых элементов.
- count: Общее количество доступных элементов.
- sort: Описание порядка сортировки.
- filter: Показывает примененные фильтры (например, фильтрация по имени "W001").

Ответы на ошибки

500 Внутренняя ошибка сервера

Код состояния: 500 Внутренняя ошибка сервера

Тело ответа:

{
  "message": "internal server error",
  "code": "internal.server.error",
  "timestamp": "2023-03-07T05:57:59.315Z"
}

Эта ошибка указывает на проблему на стороне сервера, которая помешала обработке запроса.

Резюме

Эндпоинт GET /locations предоставляет гибкий доступ к данным о локациях с поддержкой фильтрации, сортировки и быстрого поиска. Это облегчает пользователям поиск информации о локациях. В случае проблем будут возвращены соответствующие сообщения об ошибках, которые помогут устранить неполадки.

Параметры запроса​

Пример запроса​

Пример успешного ответа​

Тело ответа:​

Разбор ответа:​

Ответы на ошибки​

500 Внутренняя ошибка сервера​

Резюме​