Каковы основные стратегии версионирования API, и как выводить версию из эксплуатации?

Question

IT Interview Practice · Accepted Answer

Версионирование позволяет развивать API с **breaking changes**, не ломая существующих клиентов. Есть три основных стратегии плюс процесс вывода из эксплуатации (deprecation).

## Три стратегии

**1. URI versioning** — версия в пути.
```http
GET /v1/users/42 HTTP/1.1
GET /v2/users/42 HTTP/1.1
```
Самая простая и заметная; легко маршрутизировать, кэшировать и тестировать в браузере. Минус: технически нарушает «URI идентифицирует ресурс» (у одного пользователя теперь два URL). Это безусловно самый распространённый выбор (GitHub, исторически Stripe).

**2. Custom header versioning** — версия едет в заголовке.
```http
GET /users/42 HTTP/1.1
X-API-Version: 2
```
Сохраняет URL чистыми, но невидима в браузере и хуже кэшируется.

**3. Media-type (content negotiation) versioning** — версия в `Accept`.
```http
GET /users/42 HTTP/1.1
Accept: application/vnd.example.v2+json
```
Самая «RESTful» (URL ресурса стабилен; версионируется только его представление), но наименее удобна для потребителей.

## Что считается breaking

```text
BREAKING      → remove/rename a field, change a type, change auth, tighten validation
NON-BREAKING  → add a new optional field, add a new endpoint, add an enum value*
```
Только breaking-изменения требуют новой версии; non-breaking добавляйте в текущую.

## Процесс deprecation

1. **Объявите** с датами в документации и changelog.
2. **Сигнализируйте во время выполнения** заголовками, чтобы клиенты замечали программно:
```http
HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Jan 2026 23:59:59 GMT
Link: <https://api.example.com/v2/users/42>; rel="successor-version"
```
3. **Мониторьте** использование старой версии и связывайтесь с оставшимися вызывающими.
4. **Sunset** (отключение) только после падения использования почти до нуля.

## Почему это важно

Интервьюеры спрашивают это, чтобы понять, умеете ли вы развивать API в production, не ломая зависящих от него клиентов — реальная операционная забота, а не теоретическая. Сильнейшие ответы делают два различия: во-первых, что **большинство изменений — non-breaking** и вообще не должны вызывать bump версии (аддитивные изменения идут в текущую версию), оставляя версионирование для по-настоящему ломающих изменений; во-вторых, что *стратегия* важна меньше, чем *процесс* — именно чёткий график deprecation с заголовками `Deprecation`/`Sunset` и мониторингом использования реально защищает потребителей. URI versioning выигрывает на практике за счёт заметности и поддержки инструментами, но знание компромиссов (header и media-type сохраняют URL стабильными и более RESTful ценой обнаруживаемости) показывает, что вы понимаете пространство проектирования, а не просто копируете `/v1/`.

Три стратегии

Что считается breaking

Процесс deprecation

Почему это важно

Похожие вопросы