REST API¶

API портала построено на Django REST Framework и доступно по префиксу /api/. Схема OpenAPI генерируется drf-spectacular.

Интерактивный справочник¶

Полное описание всех эндпоинтов, полей и кодов ответа генерируется из схемы и публикуется вместе с этой документацией:

Обзор эндпоинтов с пояснениями — на странице Обзор эндпоинтов.

Сгенерировать схему локально:

./manage.py spectacular --file soniks-network-api-client/openapi.yml --validate

Клиент на Python¶

Из схемы генерируется Python-клиент — каталог soniks-network-api-client/. Это сгенерированный код, править его руками нельзя: изменения вносятся в сериализаторы и представления, после чего клиент пересобирается джобой api в CI.

Аутентификация¶

По умолчанию для всего API включены два способа:

TokenAuthentication — токен в заголовке Authorization, основной способ для клиентов станций;
SessionAuthentication — сессия Django, для запросов из веб-интерфейса.

Отдельно, только для публикации TLE (POST /api/tles/), дополнительно принимается Bearer-токен через OIDC — чтобы внешний сервис мог действовать от имени пользователя. Общепроектные классы аутентификации при этом не расширяются.

Часть эндпоинтов доступна анонимно: выдача TLE (/api/latesttles/), справочные представления и — при JOBS_ALLOW_ANONYMOUS=True — список заданий.

В схеме OIDC-токен описан отдельным механизмом oidcAuth (тип http, схема bearer, формат JWT): без этого drf-spectacular не смог бы разрешить OIDCAuthentication, и в опубликованной схеме у эндпоинта не было бы ни одного способа авторизации — при том что его единственный потребитель как раз читает схему.

Фильтрация и постраничная выдача¶

Фильтры описаны в network/api/filters.py и подключены через DjangoFilterBackend — доступные параметры для каждого эндпоинта видны в интерактивном справочнике. Размер страницы по умолчанию — ITEMS_PER_PAGE (25); для /api/tles/ используется курсорная постраничная выдача.

Ограничение частоты запросов¶

Лимиты включены точечно, а не глобально — DEFAULT_THROTTLE_CLASSES не задан, поэтому неперечисленные эндпоинты не ограничиваются:

Область	Переменная	По умолчанию
`/api/latesttles/`	`LATEST_TLES_THROTTLE_RATE`	60/мин
Аналитика	`ANALYTICS_THROTTLE_RATE`	120/мин
Тяжёлая аналитика	`ANALYTICS_HEAVY_THROTTLE_RATE`	30/мин
`/api/future_satellite_obs`	`FUTURE_OBS_THROTTLE_RATE`	20/мин
Список `/api/observations/` анонимно / с токеном	`OBSERVATIONS_LIST_ANON_THROTTLE_RATE`, `OBSERVATIONS_LIST_AUTH_THROTTLE_RATE`	60/час, 240/час
Список `/api/stations/` анонимно	`STATIONS_LIST_ANON_THROTTLE_RATE`	256/час
Кадры SIDS, `POST /api/demoddata/`	`DEMODDATA_CREATE_THROTTLE_RATE`	3600/час
Отчёт станции, `POST /api/v2/stations/<id>/status/`	`STATION_STATUS_THROTTLE_RATE`	1200/час

Авторизованный клиент считается по пользователю, поэтому все станции одного владельца делят счётчик. /api/jobs/ не ограничен намеренно: интервал опроса у старого клиента настраивается, а станция, которая не обновится, не должна заметить лимит. Анонимный клиент считается по адресу — см. NUM_PROXIES в Конфигурация.

Форматы ответа¶

JSON плюс браузерный рендерер DRF без форм (network.api.renderers.BrowsableAPIRendererWithoutForms). Выдача TLE дополнительно поддерживает ?FORMAT=tle и ?FORMAT=json.