И снова размышление о версионировании REST API. Казалось бы, его место в URI и спор может быть только о том говорить api/v1 или api/1. Но возникают все новые варианты. Вариант 1 - версионировать тела запросов, то есть добавить версию в json. Недостатки: nginx/apigee не сможет роутить запрос на нужную версию инстанса, а значит несимпатичная compatibility логика оказывается в компоненте, увеличивая его сложность(и эту логику никто не любит ни писать, ни тестировать, ну и дальше вы понимаете). Вариант 2 - Microsoft-овский - версия в query parameters https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#12-versioning. Недостатки: routing по query params потребует их парсинга, что увеличит время процессинга; а кроме того усложнится клиент, ведь ему прийдется в явном виде каждый раз формировать query parameters (или надеяться что версия не поломается, а сколько людей не читают документацию). Вариант 3 - версия в header-е https://youtu.be/P0a7PwRNLVU . Routing получше, чем вариант 2, но сложность клиента опять же возрастает с теми же рисками что в варианте 2.

Вывод. Не ставить версию в URI могут только те команды, которые уверены либо в короткой жизни продукта либо в бессмертии технического лидера (или тотальной преемственности). Потому что клиенты будут забывать ставить версию, если их не насиловать на эту тему, а логика back-compatibility в компоненте постоянно будет источником багов. Да и зачем придумывать новое, когда есть понятное дефолтное для всех решение?