# 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. Отсутствие версионирования
Отклонено — высокий риск поломки клиентов.