Ofrezco una pequeña API de servicios web para mis clientes que planeo evolucionar con el tiempo. Necesito algún tipo de control de versiones, pero no puedo encontrar información sobre cómo hacer algo así.Web Services API Versioning
¿Existe una mejor práctica?
¿Cómo puedo seguir agregando nuevas funcionalidades sin romper la compatibilidad con los consumidores de los servicios web?
Agregue el "número de versión de API" como parámetro en todas sus API y luego implemente el patrón de estrategia en su código de servicio web donde el número de versión indica qué estrategia usar.
Generalmente agrego la cadena de versión a la URL del servicio web, dándome "puntos finales versionados". El código que implementa esos puntos finales puede ser compartido, si las diferencias son triviales y pueden ser manejadas por el mismo código, o el código puede ser clonado, o en algún punto intermedio.
Los diferentes puntos finales versionados también podrían usar esquemas XML versionados, si eso es lo que necesita.
La creación de versiones es un tema complejo, por lo que primero debe definir sus objetivos de una manera más descriptiva. Sería genial decir que tienes una interfaz que asegura que nunca vas a romper la compatibilidad, pero dependiendo de cuál sea la nueva funcionalidad, es posible que ni siquiera sea posible. Entonces, hay diferentes situaciones y diferentes intercambios.
Si su intención es proporcionar nuevas funcionalidades a nuevos consumidores, y todos sus consumidores son consumidores directos (sin intermediarios, marcos, etc.), entonces un enfoque de punto final discreto es la mejor opción. Cada vez que agrega una función que arriesga una interrupción, cree un nuevo punto final, asígnele un nuevo número de versión y luego informe a los consumidores para que validen y cambien sus configuraciones. Esta estrategia es bastante probada y cierta, pero tiene los inconvenientes de poner la carga en los consumidores para mantenerse al día. Además, si hay dependencias entre los servicios, puede convertirse en una tarea rutinaria. La ventaja es que si el código se rompe, no es (directamente) tu culpa.
La otra estrategia principal es la interfaz extensible. Aquí hay tres variedades diferentes de las que tengo conocimiento. En primer lugar, es el tipo de interfaz que trata de describir tan bien el dominio del servicio que cada característica posible que puede agregar es de alguna manera posible dada la interfaz existente. Si eso suena difícil, lo es. Puede llamar a esto la interfaz perfecta. Todo está completamente descrito, pero el dominio completo también está completamente descrito. El "perfecto" en realidad solo está en papel.
La segunda variedad es del tipo que se parece a una interfaz normal pero agrega puntos de extensión genéricos. En WSDLs esto significa xs: any, pares de nombre-valor o algo similar. Puede llamar a esto la interfaz extensible básica. No es demasiado difícil de hacer, pero no sin complicaciones. Los puntos de extensión pueden hacer que la interfaz sea más difícil de trabajar en ciertas herramientas (xs: any), o perder algo de su capacidad para validar las entradas y salidas (pares nombre-valor). También es bastante fácil abusar de esos puntos de extensión de una manera que hace que la versión 3 o 4 sea bastante difícil de usar.
La tercera variedad es el tipo que convierte su interfaz en un byte-stream. Puede llamar a estas interfaces de dios. No están sin sus justificaciones, pero si está utilizando uno, es posible que desee preguntar por qué está utilizando los servicios web en absoluto. Tal vez deberías pensar en TCP/IP sin formato o HTTP GET/POST básico. Pero tal vez estés harto de la complejidad de WSDL y XSD, y solo quieres empezar de cero, pero estás ligado a los servicios web por algún motivo de infraestructura. Sin embargo, tenga en cuenta que una vez que comience por este camino, necesitará una forma completamente nueva de describir a sus consumidores cómo/no usar su servicio, y si usa XSD para eso ... bueno, básicamente está de vuelta donde tú empezaste.
Lo mejor que puede hacer es conocer todas estas opciones y acercarse al diseño de su servicio intentando primero la "interfaz perfecta", luego renunciando y agregando puntos genéricos de extensibilidad. Intentar diseñar la interfaz perfecta te obligará a aprender cosas que mejorarán tu servicio, no solo tu interfaz, pero llevará tiempo, y si no limitas ese tiempo de alguna manera, tomará una eternidad.
Un poco lejos de una verdadera interfaz de dios, existe la interfaz de la envoltura. Si su sistema tiene capas, también quiere que su interfaz esté en capas. Cuando cambie la capa B, solo desea cambiar la capa B, no todas las instancias en la capa C.
todo un poco abstracto y pastel en el cielo para mi gusto. –
¿Cómo se supone que debe ser el más específico dada la información proporcionada en la pregunta original? – HDave
Una de las posibilidades es diseñar todas las operaciones del servicio web para tener solo un parámetro de un tipo heredado de un resumen tipo que contiene el número de versión. Este enfoque está implementado por eBay web services platform. algo como lo siguiente:
<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.
Además, si se trabaja a través de http tal vez necesite añadir versión como parámetro HTTP GET al servicio web URL de punto final, por lo que será capaz de detectar la versión solicitada fácilmente http://server/service?version=1
la estrategia más común que he visto es a la versión del WSDL mediante la adición de identificación de versiones (normalmente yyyy/MM[/dd]) para el espacio de nombres de objetos en el WSDL, a saber:
targetNamespace="http://schemas.mycompany.com/2010/01/widgets"
Esto se puede hacer en un nivel por type (types/schema) o en todo el nivel WSDL - <definitions> en 1.1 o <description> en 2.0.
Un poco anticuado, pero this link de IBM Developer Works proporciona la justificación de este enfoque, y en concreto cuando las versiones tienen que ser incrementado:
revés versión compatable/cambios no separación:
cambios rotura:
Esto funcionaría sólo si los servicios web con versiones toman * exactamente * la mismos argumentos, por lo que se aplica el mismo WSDL. Si en una nueva versión requiere la adición de un nuevo atributo, ¿qué haces? –