# API-слой

Раздел описывает устройство HTTP-интерфейса, реализованного на FastAPI. Материал охватывает маршруты, правила валидации и обработку ошибок без примеров запросов.

## Маршруты

- `/api/parse/text` — принимает текст, извлекает индикаторы и возвращает сгруппированные результаты по категориям.
- `/api/tasks` — создаёт задачу на сканирование индикаторов с автоматической генерацией идентификатора.
- `/api/tasks/{task_id}` — предоставляет актуальное состояние задачи, прогресс обработки и диагностику ошибок.
- `/api/health` — возвращает готовность приложения и показатели очереди для систем мониторинга.

## Валидация и форматы

- Все методы работают с JSON и требуют заголовок `Content-Type: application/json` при передаче тела запроса.
- Схемы Pydantic проверяют обязательность полей и минимальную длину строк; списки индикаторов строятся внутри сервиса после разбора текста и не передаются клиентом напрямую.
- Ответы содержат идентификаторы задач, агрегированные вердикты, списки обработанных и ожидающих индикаторов, сохранённый исходный текст запроса и текстовые ошибки при сбоях.
- OpenAPI публикуется по путям `/api/docs` и `/api/redoc` и отражает актуальные модели запросов и ответов.

## Обработка ошибок

- Отсутствие токена обязательного провайдера приводит к серверной ошибке с указанием имени сервиса.
- Попытка создать дубликат задачи возвращает сообщение о занятости идентификатора без изменения текущей обработки.
- Запросы без обязательных полей или с пустыми значениями отклоняются с описанием нарушенных ограничений.
- Внутренние ошибки очереди, БД или сетевых вызовов возвращаются с кодом 500 и текстом причины без трассировок стека.

## Инициализация API

- Приложение создаётся в `ioc_checker/api/app.py` и регистрирует события запуска и останова для корректного закрытия подключений.
- Параметры запуска и флаг автоматической генерации OpenAPI задаются в `ioc_checker/api/__main__.py`.
- API запускается после инициализации очереди, базы данных и провайдеров; очередь и БД используются совместно, чтобы статус задачи всегда отдавался из таблицы `tasks`.
