# REST API

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

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

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

* [Интерактивный справочник API](https://sonik.space/docs/network/api-reference/index.html)
* [openapi.yml](https://sonik.space/docs/network/api-reference/openapi.yml)

Обзор эндпоинтов с пояснениями — на странице [](endpoints.md).

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

```bash
./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` в [](../configuration.md).

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

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