¿Debería generalmente desarrollarse una biblioteca de cliente para servicios REST para ayudar a prevenir roturas de API?

9

Tenemos un proyecto donde el código de IU será desarrollado por el mismo equipo pero en un lenguaje diferente (Python / Django) de la capa de servicios (REST / Java). El código para cada capa sale en diferentes repositorios de código y que pueden seguir diferentes ciclos de lanzamiento. Estoy tratando de llegar a un proceso que evite / reduzca los cambios importantes en la capa de servicios desde la perspectiva de la capa de la interfaz de usuario.

He pensado escribir pruebas de integración en el nivel de la capa de UI que ejecutaremos cada vez que construyamos la UI o la capa de servicios (estamos usando Jenkins como nuestra herramienta de CI para construir el código que está en dos repositorios Git) y si hay fallas, entonces algo en la capa de servicios se rompió y la confirmación no se acepta.

¿Sería también una buena idea (¿es una práctica recomendada?) Que el desarrollador de la capa de servicios cree y mantenga una biblioteca de cliente para el servicio REST que existe en la capa de la interfaz de usuario que actualizarán cada vez que haya un cambio importante en su API de servicio? Posiblemente, tendríamos la ventaja de una API de tipo estático con la que se construye el código de la interfaz de usuario. Si la API de la biblioteca del cliente cambia, entonces el código de la interfaz de usuario no se compilará (por lo que sabremos antes que hubo un cambio importante). También seguiría ejecutando las pruebas de integración al crear la interfaz de usuario o la capa de servicios para validar aún más que la integración entre la interfaz de usuario y los servicios todavía funciona.

rest django

— Mejores prácticas
fuente

66

¿No se le está comunicando cuando se realiza un cambio de API? En estos casos, a menudo es mejor versionar la API para que su IU siempre tenga una versión que funcione. Luego "actualice" a la última versión de API lo antes posible.

— Matt S

@MattS: estoy de acuerdo contigo. Pero con o sin comunicación: hacer una actualización a una API modificada es mucho más fácil cuando el compilador le dice exactamente todos los lugares que debe cambiar en su código. Aunque el OP todavía no nos dice cómo su código de Python proporcionará una API estática.

— Doc Brown

1

En general, para los métodos de la API que están desapareciendo, elija una convención y 'desacredítelos', especialmente tan pronto como esté disponible y probada una API de reemplazo completa. Deje la antigua API en su lugar (esencialmente), pero etiquete los metadatos de firma del método o inserte un evento de registro para que el uso pueda identificarse claramente.

Iniciar sesión en la API del servicio es una cosa, pero alertar a los clientes consumidores es otra. Para REST, no creo que haya una práctica sólida y estándar. Los clientes de la API FourSquare pueden descubrir métodos obsoletos incluso si el método llamado es exitoso (código HTTP 200, sin embargo, errorType se establecerá en 'obsoleto'). Posiblemente una estrategia razonable para proporcionar a los clientes consumidores la oportunidad de conocer un método obsoleto dentro de la API sin causar una violación.

https://developer.foursquare.com/overview/responses

Dentro de su guía de API, sugiera una fecha o número de versión de compilación donde la API en desuso se eliminará por completo. A medida que desarrolle su estrategia de desaprobación, querrá alertar a los consumidores de la API sobre cuál es la estrategia propuesta (cómo pueden descubrir métodos desaprobados, cómo hacer la transición a la API de reemplazo y cuándo la API desaprobada ya no estará disponible si purgado durante una limpieza de API), y solicite comentarios de ellos para garantizar que el proceso sea beneficioso para todos.

— JustinC
fuente

1

El control de versiones de su API es otra posibilidad. Cuando se implementa una nueva versión, deje activa la versión anterior y permita la negociación a través de la solicitud. Si mantiene las versiones 2 o 3 más recientes, el código de la interfaz de usuario puede actualizarse a su propio ritmo.

— jiggy
fuente

1

Hay al menos tres preguntas a la vez, hagámoslas una por una

"¿Es una buena idea tener una biblioteca cliente para el servicio REST?"

Lo más probable es que sí, siempre que no desee llamadas REST arbitrarias directamente dispersas a través de todo su código de UI.

"¿Es una buena idea dejar que el desarrollador de la capa de servicios cree y mantenga la biblioteca?"

Eso depende de las personas en su equipo. El mantenedor de la API debe conocer tanto las cosas disponibles en la capa de servicios como los requisitos de la capa de IU. Por lo tanto, puede ser una persona de la capa de servicios o una de la capa de interfaz de usuario, o (dependiendo del tamaño y otras tareas) una persona independiente de ambos equipos.

[obtendremos una ventaja del hecho de que] "si la API de la biblioteca del cliente cambia, entonces el código de la IU no se compilará"

¿No dijiste que la interfaz de usuario se escribirá en Python? Ese no es un lenguaje de tipo estático, por lo que no esperaría una interrupción de compilación inmediata a partir de un cambio de API. Supongo que me equivoqué en este momento y tiene una API estática aquí, entonces puede obtener algunas ventajas aquí siempre que la compilación no se rompa al agregar algunas características nuevas (como nuevos parámetros opcionales) a la API. De lo contrario, generará una sobrecarga innecesaria para su equipo.

— Doc Brown
fuente