mostovik-backend/docs/adr/ADR-014: API Versioning and Backward Compatibility Policy.md

ADR-014: API Versioning and Backward Compatibility Policy

Status

Accepted

Context

Система предоставляет API для:

• внутренних сервисов
• админ-панели
• потенциальных внешних интеграций

API развивается со временем:

• добавляются новые поля
• меняется структура ответов
• появляются новые эндпоинты
• изменяется бизнес-логика

Без политики версионирования возможны:

• поломка клиентов
• неявные регрессии
• невозможность безопасного развития API

Decision

Используется versioned API через URL:

• /api/v1/

Версия API фиксируется в URL и не изменяется неявно.

Правила изменения API

Разрешено (без изменения версии)

• добавление новых эндпоинтов
• добавление новых необязательных полей
• расширение enum-значений (если не ломает клиентов)
• улучшение производительности без изменения контракта

Запрещено без новой версии

• удаление полей
• изменение типа поля
• изменение обязательности поля
• изменение структуры ответа
• изменение семантики существующего поля

Deprecation policy

• устаревшие эндпоинты помечаются как deprecated
• поддерживаются ограниченное время
• удаляются только после явного перехода клиентов

Backward compatibility

Система гарантирует:

• сохранение контракта внутри одной версии API
• предсказуемое поведение для существующих клиентов

Consequences

Positive

• безопасное развитие API
• предсказуемость для клиентов
• снижение риска регрессий

Negative

• необходимость поддержки старых версий
• усложнение документации
• возможный рост технического долга

Alternatives considered

1. Версионирование через заголовки

Отклонено — сложнее отлаживать и документировать.

2. Отсутствие версионирования

Отклонено — высокий риск поломки клиентов.