Versioning and compatibility

API живут дольше клиентов. Предпочитайте обратно совместимую эволюцию; явную версию — только при неизбежном breaking change.

Тактики совместимости:

• **Additive changes**: новые optional fields, endpoints, enum values, которые клиенты игнорируют.
• **Tolerant readers**: клиенты игнорируют неизвестные JSON fields; серверы принимают пропущенные новые поля с defaults.
• **Deprecation windows**: заголовок Sunset, changelog, метрики по старым полям.
• **Version channels**: префикс URL (`/v2/orders`), заголовок (`Accept-Version: 2`) или media type — одна основная стратегия на API surface.

					GET /v2/orders/1
Accept: application/vnd.myapi.orders+json;version=2
				

Breaking examples, требующие новой версии или resource:

• Переименование или смена типа полей, от которых зависят клиенты.
• Изменение формы ошибок или смысла status code.
• Удаление endpoints или ужесточение validation.

На интервью: как безопасно выкатывать additive changes, обнаруживать breaking usage, мигрировать mobile и сторонних consumers.

Типовые ошибки: тихие breaking changes, несколько схем версионирования сразу, версия на каждый мелкий твик, нет телеметрии по deprecated paths.

Компромисс: видимость URL versioning против чистоты headers — важнее согласованность и документация, чем конкретный механизм.

Чеклист:

• По умолчанию additive, compatible changes.
• Документируйте срок deprecation и Sunset.
• Одна основная схема версионирования на public API.
• CI на breaking diffs OpenAPI/schema.