Public API

Публичный 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 — JSON с метаданными:

{ "CurrentPage": 1, "TotalPages": 5, "PageSize": 100, "TotalCount": 480, "HasPrevious": false, "HasNext": true }

Поле	Тип	Описание
`CurrentPage`	int	Текущая страница
`TotalPages`	int	Всего страниц
`PageSize`	int	Размер страницы
`TotalCount`	int	Всего записей
`HasPrevious`	bool	Есть предыдущая страница
`HasNext`	bool	Есть следующая страница

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

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

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.

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`)	Эндпоинт
RoadEntity	`Geojson`	`POST api/v1/public/EntityData/RouteData/{entityName}/All`
RoadEntity	`Pbf`	`GET 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):

Параметр	Тип	Описание
`FilterId`	Guid?	Идентификатор ранее зарегистрированного фильтра
`NotIn`	Guid[]	Исключить фичи по Id
`Fields`	string	Список полей через запятую (для уменьшения ответа)

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

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), список фильтров, логические операции и правила описаны в Фильтрация.

Page tree