Глосарій

Версіонування 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 і документацію.