API Versioning (версионирование API)

API versioning (версионирование API) — практика управления изменениями публичного API так, чтобы существующие клиенты продолжали работать, когда вы его развиваете. Поскольку чужие приложения, мобильные клиенты и интеграции завязаны на форму ваших ответов, нельзя просто переименовать поле или убрать эндпоинт — это молча их сломает. Версионирование даёт способ выкатывать ломающие изменения под новой версией (v1, v2), пока старая продолжает обслуживать запросы. Распространённые стратегии — на основе URL (/v1/orders), заголовка (Accept: application/vnd.api+json;version=2) или query-параметров. Более широкая дисциплина — отличать ломающие изменения (удаление поля, смена типа) от обратно совместимых (добавление необязательного поля) и повышать версию только ради первых. Для AI/SaaS-разработчиков, выпускающих публичный или партнёрский API, версионирование вместе с внятной политикой устаревания (deprecation) позволяет быстро двигаться внутри, не ломая каждого клиента. Практическая заметка: версионируйте с первого дня, даже если у вас только v1, и объявляйте сроки вывода из эксплуатации задолго до того, как что-то удалить.