Estrategias para actualizar o versionar servicios web?

Question

Me interesan las mejores prácticas sobre cómo se manejan las diferentes versiones de los servicios web.

Para aclarar, si tiene algunos métodos web expuestos como un servicio web, entonces desea agregar una característica/funcionalidad y así cambiar la firma de esas llamadas a métodos, ¿cómo manejar esto de una manera que doesn ¿Rompe a todos sus clientes que actualmente llaman al servicio?

¿Despliega el servicio en una URL diferente?

Cómo se pone una versión en el propio nombre del método (MiMetodo, etc. MyMethodv2 - uf ..)

deje pasar que en una versión como parte de la llamada al método, junto con una lista de parámetros?

¿Alguien sabe cómo Google o Amazon manejan este escenario con su extensa biblioteca de servicios web?

EDIT: Hasta ahora encontré buena información en este article from Oracle. También this blog entry en algunos detalles de Java fue útil. Todavía tengo curiosidad por ver algunos de los otros enfoques.

Answer 1

La forma típica de versionar un servicio web es que los clientes especifiquen la versión deseada. Puede permitir restricciones simples, como "> 2.0", "< 1.5" o "= 1.1". Naturalmente, desea minimizar el número de versiones compatibles para su propia cordura. Si un cliente no especifica una versión, usted asume la última.

Las técnicas para proporcionar la versión varían. Algunos defienden el uso de la URL, otros fomentan los encabezados, algunos pueden incluirlo como un parámetro de la llamada de API. Casi ninguno cambiaría el nombre del método, sin embargo. Eso es equivalente al versionamiento de "paquete" o "espacio de nombres" del enlace OSGi. Hará que la actualización sea muy difícil e impedirá que las personas actualicen más que cualquier cambio en el servicio real.

También depende de cómo acceda a sus servicios web. Si está utilizando REST, mantener la URL limpia y usar encabezados tiene más sentido (y sería trivial ingresarlo como parámetro de consulta, si fuera necesario). Si está utilizando SOAP/XMLRPC/whatever-RPC, ponerlo en la URL generalmente está bien.

Editar 5/2011 Fwiw, aunque no estoy de acuerdo, Apigee's blog recommends putting the version in the URL.

Cómo el cliente especifica que la versión es generalmente bastante fácil. Lo que es más complicado es cómo se ejecutan todas las versiones al mismo tiempo. La mayoría de los lenguajes no tienen una forma de cargar múltiples versiones de la misma biblioteca/módulo/clase/función en el mismo entorno de tiempo de ejecución (ya sea una VM, un proceso o lo que sea). El enlace OSGi que proporcionó es la solución de Java para permitir esto.

En la práctica, OSGi será excesivo para la mayoría de las situaciones. Por lo general, es más fácil derivar las solicitudes obsoletas a otro servidor o proceso.

La mejor manera de "versionar" sus servicios, sin embargo, es crear extensibilidad y flexibilidad en ellos para que permanezcan hacia adelante y hacia atrás compatibles. Eso no significa que todas las versiones deben ser compatibles entre sí, pero las versiones consecutivas deben ser compatibles entre sí.

Answer 2

Puedo decirle que la solución de crear doAPIFunction, doAPIFunctionV2, y doAPIFunctionV3, etc. no ha producido más que dolores de cabeza en el lugar donde trabajo. Agregue a eso que la falta de nombres de funciones claramente descriptivos significa todo tipo de locura.

Quiere nombres de funciones API claros, y si una API está cambiando, el objetivo sería intentar hacerlo de la manera más retrocompatible posible. Sugeriría versionar sus puntos de entrada para que cada punto de entrada admita una API estable y doFunction en example.org/api-1.0/ puede ser diferente de example.org/api-2.0 si hay buenas razones para cambiar la semántica.

Answer 3

No estoy seguro de haber entendido bien su pregunta. Pero mis 2 centavos. Si la firma del método cambia como otro parámetro nuevo, ¿por qué no puede ser opcional? Pero si se cambia un tipo de datos de parámetro existente, entonces no es aplicable.

Vota esto si está completamente equivocado. :)

Answer 4

Solía ​​ser más simple cuando podía tener el mismo nombre de método del servicio web, y diferentes parámetros, hace años. :)

Una vez que escribe un servicio web, usted está haciendo un contrato con los clientes que esto es lo que apoyará.

Para los métodos más antiguos, le sugiero que inicie sesión para ver si están siendo utilizados, y por quién, para ver si puede hacer que se actualicen.

Aparte de eso, lo mejor es escribir un nuevo método, por lo que puede tener varios nombres de funciones similares que difieren en una versión.

El problema al pasar un número de versión es que debe asegurarse de que los clientes siempre pasen un número válido, lo cual, si genera los talones, funcionará, pero si no lo hace, entonces esto es muy frágil.

Poner un número de versión en el nombre parece funcionar mejor para mí, ya que hace obvio lo que es viejo, y puede usar AOP para registrar más fácilmente las versiones anteriores de los métodos del servicio web.

Answer 5

Una forma de mitigar esto es codificar por contrato y establecer interfaces en piedra. Nunca puedes realmente cambiar las firmas de función, puedes, sin embargo, sobrecargarlas. Considere la API de .NET. Descarta algunos métodos, pero siguen funcionando porque los programas codificados pueden romperse. Se puede exponer una nueva versión del servicio en un URI diferente (v2.webservice.com) para darle una hoja de ruta nueva y la v1 debería seguir siendo compatible.