Aleksandr Meshchriakov
25176f31b4
Some checks failed
CI/CD Pipeline / Telegram Notify Success (push) Has been cancelled
CI/CD Pipeline / Run Tests (push) Has been cancelled
CI/CD Pipeline / Code Quality Checks (push) Has been cancelled
CI/CD Pipeline / Code Quality Checks (pull_request) Successful in 1m42s
CI/CD Pipeline / Run Tests (pull_request) Successful in 2m25s
CI/CD Pipeline / Telegram Notify Success (pull_request) Successful in 1m34s
82 lines
2.8 KiB
Markdown
82 lines
2.8 KiB
Markdown
# 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. Отсутствие версионирования
|
||
Отклонено — высокий риск поломки клиентов.
|