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

Версионирование API — способ менять контракт API, не ломая клиентов, которые уже используют старую версию. Когда у API есть внешние потребители (мобильное приложение, сторонние интеграции), нельзя просто взять и изменить формат ответа — старые клиенты сломаются.

Версионирование через URL — самый частый и понятный способ:

@RestController
@RequestMapping("/api/v1/users")
class UserControllerV1 { ... }

@RestController
@RequestMapping("/api/v2/users")
class UserControllerV2 { ... }   // новый формат, старый v1 продолжает работать

Копнуть глубже

Другие способы версионирования:

// через заголовок
@GetMapping(value = "/users", headers = "X-API-Version=2")

// через параметр запроса
@GetMapping(value = "/users", params = "version=2")

// через Accept-заголовок (content negotiation)
@GetMapping(value = "/users", produces = "application/vnd.company.v2+json")

Версионирование через URL — самое явное и простое для отладки (видно версию прямо в адресе, легко тестировать руками через браузер/curl), но формально менее “чисто RESTful” — URL вроде бы должен указывать на ресурс, а не на версию API. На практике большинство публичных API всё равно выбирают URL-версионирование за простоту.

Главное правило при любом подходе — обратная совместимость, пока есть активные клиенты на старой версии. Нельзя просто удалить v1, пока кто-то им пользуется — старые версии поддерживают какое-то время параллельно с новыми, объявляя дедлайн отключения (deprecation policy) заранее.

🎤 Закрыл тему, если можешь объяснить:

• зачем нужно версионирование API и пример через URL;
• другие способы версионирования и почему обратная совместимость важна (если дошёл до 2-го слоя).