Comments 11
При данном подходе может затрудниться документирование системы так как один и тот же эндпоинт возвращает не конкретное представление, а сразу несколько. Если Ваша система документирования способна это описать, то проблем не возникнет и дальнейшие правки будут согласовыватьсся быстрее.
Для OpenAPI у нас используется SwaggerHub и версионирование SemVer. Очередная версия API это фактически новый документ, связанный с предыдущим лишь общей историей изменений. Поэтому нет необходимости в рамках одного документа описывать разные версии.
При данном подходе может затрудниться документирование системы так как один и тот же эндпоинт возвращает не конкретное представление, а сразу несколько. Если Ваша система документирования способна это описать, то проблем не возникнет и дальнейшие правки будут согласовыватьсся быстрее.
Для OpenAPI у нас используется SwaggerHub и версионирование SemVer. Очередная версия API это фактически новый документ, связанный с предыдущим лишь общей историей изменений. Поэтому нет необходимости в рамках одного документа описывать разные версии.
Отличный подход. У нас есть тоже своя система документирования и в какой-то момент, хотелось бы чтобы на каждую версию формировался отдельный документ и была хорошо отлеживаемая история версия) Пока это описываем ручками(декларативно в коде) и держим старые версии эндпоинтов/дто, чтобы можно было отслеживать изменения
У вас ссылка на микроблог сломалась ;(
Спасибо за статью. Интересно, насколько тяжко часто делать миграцию полей в мобильных приложениях?) Есть ещё какие тактики конкретно для мобильных приложений, чтобы совладать с миграционным адом в коде?
Почему сломалась? Сейчас проверил - все окей. Ну а чтобы совладать с миграционным адом - поддерживать сервера с разными версиями, как было написано в начале статьи:
может себе позволить содержать сервера с разными версиями серверного приложения (api.host.v1, api.host.v2) и умеет их грамотно поддерживать
В этом случае не нужно поддерживать большинство старого кода. Нужно просто содержать сервера со старыми версиями до полного отказа мобильных клиентов от старых версий, тогда и утилизировать старые сервера.
Что только не придумают, лишь бы 1С не использовать ;)
(это если что ответ на вопрос в конце статьи)
Кажется ставить версию апи в конце запроса не лучшая идея. Обычно это /api/v1/user.
Ну и практика показывает, что эти версии редко меняются))
А если это минорная версия конкретного эндпоинта, а не мажорная всего API? Я придерживаюсь подхода установки версии после /api в случаях с мажорными апдейтами всего сервиса. В Вашем случае при мажорном переезде всего API версия /api/v1 может быть занята у эндпоинта в котором Вы делали минорный фикс. И что, в этом случае у Вас будет /api/v2 для одного эндпоинта вместо /api/v1 для всех?
Не согласен с частотой изменения этих версий. В мобильном деве приходилось иметь вплоть до 2-3 версий (из-за необходимости поддерживать эндпоинты для старых версий приложения) и это было далеко не крупное приложение.
Версионная миграция данных в мире DTO