You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 6 Current »

Публичный API — доступен по префиксу public/ и защищён api-key

Авторизация

  • Все запросы требуют заголовок X-Api-Key: <ваш-ключ> (схема аутентификации ApiKey).
  • Отсутствие или невалидный ключ → 401 Unauthorized.
  • Api-key пользователь получает и перевыпускает через UI системы (в личном кабинете).

Ограничение частоты (rate limit)

  • Не более 60 запросов в минуту на один api-key (фиксированное окно).
  • При превышении → 429 Too Many Requests с заголовком Retry-After: 60.

Базовый маршрут и версия

  • Все маршруты резолвятся с префиксом версии и public: api/v1/public/....
  • Ниже маршруты приводятся относительно этого префикса.

Swagger

  • Документация Swagger публичного API доступна по пути public-api/swagger (группа public).

Заголовок X-Pagination

Эндпоинты с постраничной выдачей возвращают заголовок X-Pagination — JSON с метаданными:

{ "CurrentPage": 1, "TotalPages": 5, "PageSize": 100, "TotalCount": 480, "HasPrevious": false, "HasNext": true }
ПолеТипОписание
CurrentPageintТекущая страница
TotalPagesintВсего страниц
PageSizeintРазмер страницы
TotalCountintВсего записей
HasPreviousboolЕсть предыдущая страница
HasNextboolЕсть следующая страница

Цикл получения данных

Общая последовательность: получить список источников → определить тип и формат слоя → запросить данные соответствующим эндпоинтом.

1. Список источников данных

GET api/v1/public/Config/DataSources → List<DataSourceConfigDto>.

В публичном API значимы только источники с FeatureSourceType = RoadEntity (дорожная сущность) или RoadAccidents (ДТП). Источники других типов потребитель может игнорировать.

Поля DataSourceConfigDto: Id, ProjectId, Name, LayerType, FeatureSourceType, GeometryTypes, AccessType, Reports.

2. Количество фич по источникам

GET api/v1/public/Config/DataSources/count → Dictionary<Guid, DataSourceFeatureCount?> (ключ — dataSourceId). DataSourceFeatureCount: Count (int?) или Error (string?).

3. Конфигурация фич RoadEntity

GET api/v1/public/Config/FeatureSources/RoadEntity/{dataSourceId} → RoadEntityFeatureSourceConfigDto.

Важны FeatureConfig и FeatureConfig.EntityName. По FeatureConfig известно, как называются поля сущности и по каким полям доступна фильтрация. EntityName используется как {entityName} в маршрутах шага 6. Подробное описание структуры FeatureConfig (группы полей, типы, поля-связи) — в FeatureConfig.

4. Конфигурация слоя (стиль)

GET api/v1/public/Config/Layer/{dataSourceId} → LayerConfigDto.

  • StyleProperties (string[]) — поля, необходимые для отрисовки. При запросе данных достаточно передать только эти поля (через параметр Fields, строкой через запятую), чтобы уменьшить ответ.
  • StyleConfigs (LayerStyleConfigDto[]): Style — стиль для mapbox (JSON), Order, Name.
  • Прочие поля: Legend, ZIndexGroupType, LayerType, LayerSourceType.

5. Источник слоя (формат)

GET api/v1/public/Config/LayerSources/Backend/{dataSourceId} → BackendLayerSourceConfigDto.

Важно поле Type: Geojson либо Pbf — оно определяет способ получения данных в шаге 6. Значения приходят в PascalCase (перечисление LayerSourceFormatClassifier). Также есть SourceConfig (JSON).

6. Получение данных

ИсточникФормат (Type)Эндпоинт
RoadEntityGeojsonPOST api/v1/public/EntityData/RouteData/{entityName}/All
RoadEntityPbfGET api/v1/public/Layer/tile/vector/{entityName}/{dataSourceId}/{z}/{x}/{y}.pbf
RoadAccidents—POST api/v1/public/RoadAccidents/layer/{dataSourceId}

RouteDataController (RoadEntity, Geojson)

POST api/v1/public/EntityData/RouteData/{entityName}/All → PagedList<Dictionary<string, object?>>

  • заголовок X-Pagination.
  • Query (EntityDataParameters): DataSourceId, Fields, IsReverse, PageNumber, PageSize, OrderBy.
  • Тело: массив FilterContainer (см. Фильтрация).
  • Абстрактный эндпоинт: работает с 400+ сущностей, конкретная выбирается по {entityName}.
  • Используется как для отображения на карте, так и для карточки объекта.
  • Совместно с FeatureConfig (шаг 3) известно, какие поля возвращаются и по каким доступна фильтрация.
  • Поля-связи возвращаются как идентификаторы. Пример: у автобусной остановки поле routeId — чтобы показать читаемое значение, нужно запросить все дороги, построить словарь id → значение и подставить его на фронте.

PublicLayerController (RoadEntity, Pbf)

Векторные тайлы дорожной сущности. Так как структура фильтра может быть очень большой, применяется двухшаговый подход: сначала фильтр регистрируется и возвращает filterId, затем filterId передаётся в запрос тайла.

Регистрация фильтра

POST api/v1/public/Layer/filter — тело: массив FilterContainer → filterId (Guid).

Векторный тайл

GET api/v1/public/Layer/tile/vector/{entityName}/{dataSourceId}/{z}/{x}/{y}.pbf → application/x-protobuf (пустой тайл → 204 No Content).

Query (FeatureQueryControllerDto):

ПараметрТипОписание
FilterIdGuid?Идентификатор ранее зарегистрированного фильтра
NotInGuid[]Исключить фичи по Id
FieldsstringСписок полей через запятую (для уменьшения ответа)

Метаданные слоя

GET api/v1/public/Layer/meta/{entityName}/{dataSourceId}?filterId= → LayerMeta: Count (число фич) и Extent (полигон — охват слоя).

PublicRoadAccidentsController (RoadAccidents)

POST api/v1/public/RoadAccidents/layer/{dataSourceId} — тело: FilterAccidentDto → GeoJSON FeatureCollection точек ДТП.

Поля FilterAccidentDto: LightningTypes, RoadTypes, AccidentTypes, UdsTypes (string[]), Time, Geometry (полигон), IsInConcentration.

Дополнительные эндпоинты контроллера (счётчик, короткая выдача, слой концентрации, отдельное ДТП) описаны в Swagger.

Фильтрация

Структура FilterContainer (NextFilterLogicOperationType, FilterType, Value), список фильтров, логические операции и правила описаны в Фильтрация.

  • No labels