Веб-сервисы управление версиями API

Add the "API version number" as parameter in all your API's then implement strategy pattern in your web service code where version number dictates what strategy to use.

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

Различные конечные точки с поддержкой версий могут также использовать схемы XML с поддержкой версий, если это то, что вам нужно.

Одна из возможностей - спроектировать все операции веб-службы так, чтобы они имели только один параметр типа который наследуется от некоторого абстрактного типа, содержащего номер версии. Этот подход реализуется платформой веб-сервисов eBay . Примерно следующее:

<xsd:complexType name="AbstractRequestType">
  <xsd:attribute name="version" type="string" />
  ....

<xsd:complexType name="AddCustomerRequestType">
  <xsd:complexContent>
   <xsd:extension base="AbstractRequestType">
   ....

then use AddCustomerRequestType as a type of only parameter 
in addCustomer web service operation.

Кроме того, если вы работаете через http, вам может потребоваться добавить версию в качестве параметра http GET в URL-адрес конечной точки веб-службы, чтобы вы могли легко определить запрошенную версию http: // server / service? Version = 1

Управление версиями - сложная тема, поэтому сначала вам нужно определить свои цели более наглядно. Было бы здорово сказать, что у вас есть интерфейс, который гарантирует, что вы никогда не нарушите совместимость, но в зависимости от новой функциональности это может быть даже невозможно. Таким образом, существуют разные ситуации и разные компромиссы.

Если вы намерены предоставить новые функции только новым потребителям, и все ваши потребители являются прямыми потребителями (без посредников, фреймворков и т. Д.), Тогда подход с дискретной конечной точкой лучший выбор. Каждый раз, когда вы добавляете функцию, которая рискует выйти из строя, создавайте новую конечную точку, дайте ей новый номер версии, а затем дайте понять потребителям, чтобы они проверяли ее и меняли свои конфигурации. Эта стратегия довольно проверенная и верная, но у него есть недостатки, заключающиеся в том, что на потребителей ложится бремя необходимости быть в курсе последних событий. Кроме того, если между сервисами существуют зависимости, это может стать рутиной для отслеживания. Положительным моментом является то, что если код ломается, это не (напрямую) ваша вина.

Другая основная стратегия - это расширяемый интерфейс. Мне известно о трех различных разновидностях. Во-первых, это тип интерфейса, который пытается настолько хорошо описать домен службы, что каждая возможная функция, которую вы могли бы добавить, каким-то образом возможна с учетом существующего интерфейса. Если это звучит сложно, это так. Вы можете назвать это идеальным интерфейсом. Все полностью описано, но также полностью описана вся область. «Идеальное» действительно только на бумаге.

Вторая разновидность - это тип, который выглядит как обычный интерфейс, но добавляет общие точки расширения. В WSDL это означает xs: any, пары имя-значение или что-то подобное. Вы можете назвать это базовым расширяемым интерфейсом. Это не так уж сложно, но не без осложнений. Точки расширения могут затруднить работу с интерфейсом в определенных инструментах (xs: any) или явно потерять часть вашей способности проверять входные и выходные данные (пары имя-значение). Также довольно легко злоупотребить этими точками расширения, что затрудняет использование версии 3 или 4.

Третья разновидность - это тип, который преобразует ваш интерфейс в поток байтов. Вы могли бы назвать эти интерфейсы бога. У них есть свои оправдания, но если вы их используете, вы можете спросить, зачем вы вообще пользуетесь веб-сервисами. Возможно, вам стоит подумать о необработанном TCP / IP или простом HTTP GET / POST. Но может ты? Вы устали от сложности WSDL и XSD, и вы просто хотите начать с нуля, но по какой-то инфраструктурной причине вы привязаны к веб-сервисам. Однако поймите, что как только вы начнете идти по этому пути, вам понадобится совершенно новый способ описания потребителям, как / не использовать ваш сервис, и если вы используете для этого XSD ... ну, вы в основном вернулись туда, где вы начали.

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

Немного не хватает интерфейса истинного бога, есть интерфейс оболочки. Если в вашей системе есть слои, вы хотите, чтобы ваш интерфейс тоже был слоистым. Когда вы меняете слой B, вы хотите изменить только слой B, а не все экземпляры в слое C.