Стратегии обновления или управления версиями веб-сервисов?

Question

Мне интересно услышать лучшие практики о том, как обрабатываются разные версии веб-сервисов.

Чтобы уточнить, если у вас есть некоторые веб-методы, представленные в качестве веб-службы, вы хотите добавить функцию / функциональность и, таким образом, изменить сигнатуру этих вызовов методов, как вы справляетесь с этим способом, который не ' не сломать всех ваших клиентов, которые в данный момент звонят в службу?

Развертываете ли вы службу по другому URL-адресу?

Вы ставите версию в самом имени метода (MyMethod, MyMethodv2 и т. Д. - тьфу ..)

Передаете ли вы версию как часть вызова метода вместе со списком параметров?

Кто-нибудь знает, как Google или Amazon справляются с этим сценарием благодаря своей обширной библиотеке веб-служб?

РЕДАКТИРОВАТЬ: До сих пор я нашел некоторую хорошую информацию в этой статье от Oracle . Также эта запись в блоге о некоторых особенностях Java была полезна. Мне все еще любопытно увидеть некоторые другие подходы.

Answer 1

Типичный способ управления версиями веб-службы заключается в том, чтобы клиенты указывали желаемую версию. Вы можете учесть простые ограничения, такие как «> 2.0», «<1.5» или «= 1.1». Естественно, вы хотите минимизировать количество поддерживаемых версий для вашего собственного здравомыслия. Если клиент не указывает версию, вы принимаете самую последнюю версию. </p>

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

Это также зависит от того, как вы получаете доступ к вашим веб-сервисам. Если вы используете REST, то поддержание чистоты URL и использование заголовков наиболее целесообразно (и было бы тривиально взломать его как параметр запроса, если это необходимо). Если вы используете SOAP / XMLRPC / what-RPC, то, как правило, помещать его в URL-адрес вполне нормально.

Изменить 5/2011 FWIW, хотя я не согласен, Блог Apigee рекомендует поместить версию в URL .

Как клиент определяет версию, обычно довольно просто. Что сложнее, так это то, как вы запускаете все версии одновременно. Большинство языков не имеют возможности загружать несколько версий одной и той же библиотеки / модуля / класса / функции в одну среду выполнения (будь то виртуальная машина, процесс или что-то еще). Предоставленная вами ссылка на OSGi является решением Java, позволяющим это сделать.

На практике OSGi будет излишним для большинства ситуаций. Обычно проще отменить прокси-запросы на другой сервер или процесс.

Тем не менее, лучший способ «версий» ваших сервисов состоит в том, чтобы встроить в них расширяемость и гибкость, чтобы они оставались совместимыми в прямом и обратном направлении. Это не означает, что все версии должны быть совместимы друг с другом, но последовательные версии должны быть совместимы друг с другом.

Answer 2

Я могу вам сказать, что решение по созданию doAPIFunction, doAPIFunctionV2, doAPIFunctionV3 и т. Д. Вызвало только головную боль в том месте, где я работаю. Добавьте к этому отсутствие четко описывающих названий функций, что означает все виды безумия.

Вам нужны четкие имена функций API, и если API меняется, цель состоит в том, чтобы попытаться сделать это как можно более обратно совместимым способом. Я бы посоветовал создавать версии ваших точек входа, чтобы каждая точка входа поддерживала стабильный API, и doFunction в example.org/api-1.0/ может отличаться от example.org/api-2.0, если была веская причина для изменения семантики.

Answer 3

Раньше было проще, когда вы могли иметь одно и то же имя метода веб-сервиса и разные параметры много лет назад. :)

Как только вы пишете веб-сервис, вы заключаете с клиентами договор о том, что это то, что вы будете поддерживать.

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

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

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

Мне кажется, что лучше всего указывать номер версии в имени, так как она делает очевидным, что является старым, и вы можете использовать AOP для более удобной регистрации старых версий методов веб-сервиса.

Answer 4

Я не уверен, правильно ли я понял ваш вопрос. Но мои 2 цента. Если сигнатура метода изменяется как новый параметр, то почему это нельзя сделать необязательным? Но если тип данных существующего параметра изменяется, он не применим.

Проголосуйте, если это не так. :)

Answer 5

Одним из способов смягчения этого является кодирование по контракту и установка интерфейсов в камне. Вы никогда не сможете изменить сигнатуры функций, вы можете их перегрузить. Рассмотрим .NET API. Некоторые методы устарели, но они продолжают работать, потому что программы, закодированные вокруг них, могут сломаться. Новая версия сервиса может быть представлена ​​на другом URI (v2.webservice.com), чтобы дать ему новую дорожную карту, и v1 необходимо будет продолжать поддерживать.