Версионирование через путь — самый популярный подход, но не единственный и не всегда самый удобный для клиентов вашего API.
Самый распространённый подход: /v1/orders, /v2/orders. Плюс — простота и наглядность в логах. Минус — версия становится частью URL ресурса, что усложняет постепенную миграцию отдельных полей без полного дублирования эндпоинта.
Клиент указывает версию в заголовке, например Accept: application/vnd.hexly.v2+json. URL остаётся стабильным, что удобнее для кэширования и работы с REST-принципами, но требует более дисциплинированной работы с документацией — версия не видна в адресной строке.
На практике мы советуем версionировать по пути только мажорные несовместимые изменения, а мелкие аддитивные изменения (новые необязательные поля) добавлять без смены версии — большинство клиентских библиотек это переживают безболезненно.
Разумный ориентир — минимум 12 месяцев с момента анонса нового мажорного изменения и деprecation warning в заголовке ответа задолго до отключения. В Hexly устаревшие маршруты автоматически получают заголовок Sunset согласно RFC 8594.
Начните с бесплатного плана и подключите первый маршрут за 5 минут.