Про версионирование API, по итогам нескольких обсуждений: очень сильно зависит, что у вас за API (внутреннее или внешнее), кто ваши клиенты и насколько вы зависите от них (или они от вас).

Например, если ваше API — внешнее, а клиенты сильно зависят от вас, и вы хотите, чтобы они быстрее переходили на новые версии API — бейте лампочки в подъездах ставьте версию API в путь и давайте окно для перехода (несколько месяцев). У клиентов не будет других вариантов, кроме как перейти на новую версию — иначе у них очень грубо сломаются все вызовы, будут выдавать просто 404. Зато не будет шансов, что будет пропущена ошибка или сломается логика из-за разных форматов. Умерла так умерла. Так делают facebook (экстремистская деятельность которой запрещена на территории РФ), twitter и tiktok.

Facebook дает 90-дневный период для перехода, а X обещает не вносить ломающих изменений чаще, чем раз в год.

Кроме того, указание версии в пути позволяет легко отследить число клиентов, использующих каждую версию, по логам. Также не возникает проблемы с кэшем — не случится так, что закэшировалась старая версия. Правда, в URL возникает постоянное мерцание, и их нельзя сохранять — для старых ресурсов они испортятся (вопрос — по логике вашего бизнеса, может ли у клиента возникнуть потребность долго хранить URL ресурсов?)

Доходит иногда до смешного: в API платежного сервиса Stripe, судя по всему, сначала собирались использовать версионирование через путь (/v1/), но потом перешли на хедер Stripe-Version, который переключает(!) версию API, используемую этим клиентом. Если вы отправляете запрос с этим хедером, сервер запомнит, какую версию вы использовали, и остальные запросы будет обрабатывать как к этой версии. Это уже хранение состояния на сервере!

А вот VK принимает версию в параметре, но этот параметр является обязательным. Так у вас не меняется путь, но замусоривается хвост URL. Зато можно добавить параметр для версии, если вы забыли про него с самого начала.

Чтобы не замусоривались URL'ы, а вы сильно зависите от ваших клиентов — лучше не менять URL'ы, и давать возможность указать версию в параметрах или в хедере. Все варианты с хедером добавляют дополнительных мыслей разработчикам — теперь им ещё и про хедеры нужно думать. Тут возникают риски поймать ошибку: во-первых, эту штуку с хедерами тяжело тестировать, во-вторых — если мы меняем все пути в приложении, то подумаем и про остальные изменения.

Ещё один аргумент пуристов RESTа, что обсуждение версии ресурса — это часть обсуждения типа контента между клиентом и сервером. Клиент сообщает серверу о версии контента, который может принимать клиент, поэтому версия должна быть в хедере Accept: application/vnd.myapi.v2+json

В этом смысле интересно услышать мнение Роя Филдинга про версионирование. Оно очень короткое:

DON'T

Чуть подробнее Филдинг обрушивается на версионирование через версию в пути:

a "v1" is a middle finger to your API customers, indicating RPC/HTTP (not REST)

А правильный ответ, конечно, HATEOAS (чего бы мы ещё могли ждать от Филдинга).

"hypermedia as the engine of application state" is a REST constraint. Not an option. Not an ideal. Hypermedia is a constraint. As in, you either do it or you aren’t doing REST. You can’t have evolvability if clients have their controls baked into their design at deployment. Controls have to be learned on the fly. That’s what hypermedia enables.

Типа, если вы меняете структуру ответов и даже API — выразите это в ссылках, через гипермедиа. А если у вас изменения, которые должны сломать всех клиентов — значит, у вас новая система, меняйте не версию API, а сразу доменное имя — ведь теперь это другая система, верно? 🤯🤦🏼‍♂️

Вот это уже шестой вариант версионирования — через имя домена. Ну действительно — меняем api.server.com на api2.server.com. Интересная мысль!