Глоссарий

Версионирование API

Версионирование API — подход к управлению изменениями в API, позволяющий обновлять его без поломки существующих клиентов. API меняется со временем, но клиенты, использующие старую версию, должны продолжать работать.

Стратегии

URL versioning — /api/v1/users, /api/v2/users. Наиболее явное, легко кешируется. Самый популярный подход
Header versioning — Accept: application/vnd.api+json; version=2. Чище URL, но сложнее клиент
Query parameter — /api/users?version=2. Просто, но засоряет URL

Правила breaking change

Удаление поля — breaking change → новая major version
Добавление поля — обычно non-breaking (если клиенты игнорируют неизвестные поля)
Изменение типа поля — breaking change

Deprecation

Поддерживайте старую версию минимум 6–12 месяцев после объявления устаревшей. Уведомляйте клиентов через заголовок Sunset и документацию.