Как вы обрабатываете версионирование в RESTful API?

Версионируют прежде всего несовместимые изменения контракта: путь /v1, заголовок или media type. Совместимые добавления часто можно выпускать без новой версии при аккуратном контракте.

Нужны схема API, contract tests, политика deprecated и срок поддержки клиентов. Новая версия не устраняет необходимость миграции данных и наблюдения за старым трафиком. Не меняйте незаметно смысл поля, тип или обязательность. Особенно важно учитывать выпущенные мобильные и desktop-клиенты, которые обновляются не одновременно с backend.