REST API versioning

Question

В настоящее время я работаю над веб-приложением на основе Java. Недавно мы создали некоторые конечные точки REST с использованием Spring. Причина этого заключалась в том, что мы разработали гибридное мобильное приложение, которое интегрируется с нашим основным приложением через эти конечные точки.

Проблема в том, что в будущем мы не совсем уверены, как обрабатывать обновления. Если мы обновим наш API, например. мы меняем сигнатуры методов методов конечных точек или меняем атрибуты на DTO, которые мы возвращаем как JSON, тогда у нас возникнет проблема, если наши мобильные пользователи будут запускать устаревшую версию мобильного приложения.

Что мы хотим реализовать, это то, что заставит наших пользователей обновлять приложение, если оно устарело. Я видел много мобильных приложений, которые это делают. Поэтому мы подумали о том, чтобы иметь версию API для нашего REST API, а затем проверить мобильное приложение, если используемая версия такая же, как версия, выполняемая нашим сервером, а если нет, то заставить пользователя сделать обновление.

Проблемы у нас есть следующие:

1. У нас есть только одна версия нашего сервера работает в любое время. Итак, как мы будем время выпускать наши релизы? Что произойдет в том случае, если мы выпустим новую версию нашего API и нашего мобильного приложения, но в магазине приложений пока нет доступной последней версии. Затем пользователь будет вынужден выполнять обновление, но обновленное приложение еще не доступно для них.

2. Как мы поддерживаем номер версии API? В мобильном приложении мы можем просто настроить это. Но на сервере неплохо поддерживать номер версии. Причина, по которой я говорю это, - это то, что если мы вносим изменения в сигнатуру метода или DTO и т. Д., И забываем обновить этот номер версии вручную до выпуска? Разумеется, существует более автоматический способ сделать это, когда создается уникальный «ключ API» на основе текущего определения API? Тогда мы могли бы использовать это вместо номера версии API.

Answer 1

Похоже, вам необходимо сделать обратные совместимые обновления с вашим API.

Поскольку вы контролируете код клиента, вызывающий API на мобильной стороне, просто скопируйте приложение, чтобы игнорировать новые поля, которые появляются в ответах JSON. Это сделает приложение гораздо менее хрупким и позволит вам по желанию расширить свои объекты. Максимально используйте HATEOAS и попросите своих клиентов перемещаться по гиперссылкам внутри ваших объектов, а не жестко привязывать их к вашей структуре URL.

Необходимо начать культуру и процесс тестирования совместимости с каждой версией сервера, чтобы вы могли автоматически проверить, что ваши старые клиенты API (которые, конечно же, будут жить навсегда на телефонах людей, которые никогда не обновляют свои приложения) будут по-прежнему работать с обновлением, которое вы планируете для своего сервера. В Semantic Versioning это похоже на то, что вы обновили до версии API.

Если вы считаете, что на каком-то этапе вам нужно будет существенно изменить совместимость API, которая сломает ваши старые приложения, а затем с самого начала создайте «проверку совместимости» с вашими клиентами API. При запуске они должны проверить простой API на сервере, чтобы выполнить рукопожатие базовой версии. Если сервер отвечает «мы просто не можем больше поддерживать ваш старый клиентский код», тогда вы получите сообщение об ошибке приложения с сообщением о том, что пользователь вытащил последнюю версию из магазина приложений. Но так как это довольно неприятный пользовательский интерфейс, лучше просто создать разумную совместимость с самого начала.

Answer 2

Есть несколько вещей, которые вы можете сделать.

1. Архитектор API версии с самого начала. Есть два общих подхода, которые я видел для этого с помощью REST API: ставьте префикс URL как /v1, /v2 и т. Д. Перед всеми конечными точками ресурса REST или используя заголовок HTTP Accepts для согласования версий. Есть религиозные войны, на которых человек прав. Это ваш API. Делайте то, что считаете правильным.
2. Извлечь бизнес-логику из кода конечной точки API в вашем исходном коде. Таким образом, вы можете иметь конечную точку v1 и v2, которые повторно используют общий код на уровне обслуживания более низкого уровня. Это то, что вам не нужно делать с самого начала. Вы можете подождать, пока v2 API не начнет разделять все.
3. Автоматическое тестирование каждой сборки по сравнению с существующими версиями API (и любой новой версии, которую вы строите, но регрессионное тестирование является ключевым моментом, который я делаю).
4. Принудительное обновление приложений или, по крайней мере, отслеживание использования версии приложения, позволяет вам удалить/очистить любой код, поддерживающий устаревшие версии.

Я работаю над аналогичным проектом, создавая новый REST API для нового мобильного приложения. Я разделяю пространство URL по версии, поэтому https://api.blahblahblah/v1.0/resource.

На данный момент у меня есть моя бизнес-логика, встроенная прямо в код, который принимает HTTP-запросы, потому что для такой логики нет другого использования. Однако, когда мне нужно создать новую версию, я реорганизую код API v1, чтобы отделить все, что не является v1-специфичным, в более повторно используемый модуль, который затем может быть повторно использован.

В зависимости от того, насколько структурно отличаются ваши версии, вам может потребоваться некоторое сокращение, чтобы ваш API был отделен. Например, возможно, вам нужен общий объект UserEntity для представления информации о пользователе из вашей базы данных, но для этого требуется объект UserV1Resource и UserV2Resource для отдельных версий с адаптерами или другим шаблоном проектирования для оповещения о различных типах, которые передаются в JSON или XML.

Имея автоматизированные тесты API, я могу свободно выполнять любой из этих рефакторингов, разделяя их, когда я пойду, зная, что в тот момент, когда я нарушу совместимость с прошлой версией, мои тесты будут кричать на меня.

До сих пор приятным преимуществом API, которое сейчас используется нашим мобильным приложением, является то, что нам нужно только беспокоиться о совместимости с поддерживаемыми версиями приложений. Если мы сможем убедиться, что наши конечные пользователи регулярно обновляют свое приложение, мы сможем удалить старые версии, что поможет свести к минимуму наш технический долг.