Обзор API

Базовый URL

Все API-эндпоинты доступны по пути /api/v1:

https://slozy.net/api/v1

Для локальной разработки:

http://localhost:8080/api/v1

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

API использует JWT Bearer-токены. Токен передаётся в заголовке Authorization:

Authorization: Bearer <access_token>

Получить токен можно через эндпоинты /auth/register и /auth/login. Токен живёт 8 часов (настраивается через JWT_EXPIRATION). По истечении токен обновляется через /auth/refresh.

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

Все ответы возвращаются в JSON. Успешные ответы:

{
  "success": true,
  "data": { ... }
}

Ответы со списками поддерживают пагинацию:

{
  "success": true,
  "data": {
    "items": [],
    "total": 42,
    "page": 1,
    "page_size": 10,
    "has_next": true
  }
}

Ответы с ошибками:

{
  "success": false,
  "error": "Описание ошибки",
  "details": "Детали (могут отсутствовать)"
}

HTTP-статусы

Код	Описание
200	Успешный запрос
201	Успешное создание
204	Успешное удаление
400	Некорректный запрос
401	Не авторизован
403	Доступ запрещён
404	Ресурс не найден
413	Слишком большое тело запроса
429	Превышен rate limit
500	Внутренняя ошибка сервера

Rate Limiting

Действуют два уровня ограничений:

• Глобальный: 1000 запросов в минуту
• На IP: 100 запросов в минуту

При превышении возвращается 429 Too Many Requests. Заголовки ответа содержат информацию о лимитах:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 2026-06-11T14:00:00Z

Версионирование

API версионируется через путь: /api/v1/, /api/v2/ и т.д. Обратная совместимость в рамках одной мажорной версии гарантируется. Изменения, нарушающие совместимость, публикуются в release notes.

Группы эндпоинтов

Группа	Префикс	Описание
Auth	/api/v1/auth	Регистрация, вход, выход, обновление токенов
SLO	/api/v1/slos	CRUD для Service Level Objectives
Prometheus	/api/v1/prometheus	SLO-расчёты, метрики в реальном времени
Notifications	/api/v1/notifications	Каналы оповещений, правила, история
Cache	/api/v1/cache	Управление кэшем, статистика, конфигурация
Health	/api/v1/health	Проверки состояния сервиса