En la primera parte de la publicación sobre nuestra propuesta de validación de APIs dentro de un flujo de integración continua vimos cómo garantizar el cumplimiento del contrato mediante tests con Postman y Newman.

En esta parte veremos cómo conseguir los otros dos objetivos que se marcaron en el flujo de validación: por un lado, c****ontrolar los cambios que verdaderamente se están subiendo en una release mediante una librería de comparación de definición de APIs: swagger-diff. Y por otro, cotejar la calidad del contrato de nuestra API mediante la definición de reglas de calidad y la comprobación de su cumplimiento mediante la librería Speccy.

Comprobación de cambios a desplegar

Uno de los puntos claves en el gobierno e implementación de APIs es el control y la gestión de cambios entre versiones mediante la detección de modificaciones no retrocompatibles respecto los servicios que actualmente se están consumiendo.

Existen diferentes librerías que nos permiten de una manera automatizada la detección de cambios entre diferentes versiones de Open API Specification y, entre esos cambios, la identificación de aquellos que rompen el contrato actual.

La incorporación de este tipo de herramientas en un pipeline de integración continua nos sirve para:

En el mercado hay diferentes librerías que ofrecen esta funcionalidad, en la siguiente tabla se muestran algunas de ellas:

Todas ellas ofrecen, a través de línea de comandos, la detección de cambios entre versiones de OAS. Luego, a nivel de integración en el pipeline, ninguna herramienta es mejor que otra, pero sí hay diferencias si comparamos el nivel de detección de cambios.

En la siguiente tabla listamos los cambios, especialmente los no retrocompatibles que se probaron entre dos versiones de OAS 2.0 con las dos primeras librerías y OAS 3.0 con la tercera librería para comprobar si los detectan o no. La última opción se descarta por falta de actividad y mantenimiento de la misma durante más de dos años.

Como se ve en la tabla comparativa, la segunda librería apenas detecta cambios relevantes, mientras que la primera y la tercera sí. Después, dependiendo de qué versión de OAS se utilice para definir los contratos, se puede hacer uso de una de estas librerías dentro de nuestro pipeline.

Si queremos comprobar los cambios entre dos versiones de OAS 2.0 podemos hacer uso de la primera librería. Con la cual podemos:

Un ejemplo de la salida del comando anterior sería la siguiente:

Un ejemplo de la salida del comando anterior con cambios no retrocompatibles sería el siguiente:

En caso de que no existan cambios que rompan el contrato no se devuelve nada en la salida del comando anterior.

Si queremos comprobar los cambios entre dos versiones de OAS 3.0**,** podemos hacer uso de la tercera librería con la cual, además de detectar los cambios no retrocompatibles y listar todos los cambios entre versiones, permite obtener esa información en formato markdown y html. Aquí podemos ver el ejemplo:

Calidad del contrato

Otro punto clave es la normalización de los contratos definidos en nuestros Swagger para representar de una manera homogénea todas las APIs que forman parte de una organización y sus aplicaciones.

Si bien es cierto que el punto clave es definir el conjunto de buenas prácticas para conseguir esa homogeneización, también es cierto que la revisión para comprobar el cumplimiento de esas buenas prácticas es muy tedioso.

Otro aspecto a tener en cuenta es la medición de lacalidad de los contratos****. Es complicado justificar que un contrato de una API sea bueno o malo, ya que se trata de algo muy subjetivo, pero la manera de hacerlo es transformando algo cualitativo en algo cuantitativo que nos ayude a medir esa calidad y el cumplimiento de la normas establecidas.

Con el objetivo de conseguir esa homogeneización de una manera automática y la medición de la calidad de los contratos desplegados de una manera cuantitativa nos ayuda Speccy. Speccy es un motor de reglas que nos permite validar la definición de APIs en formato OAS 3.0.

Está desarrollada en Node.js y su funcionamiento radica en verificar si el fichero de definición de API cumple una serie de reglas definidas en un fichero yaml denominado ruleset**,** con el objetivo de que las definiciones sean lo más consistente posible y cumplan con la estrategia de gobierno y sus buenas prácticas.

Speccy incluye por defecto dos rulesets predefinidos en la carpeta de ese mismo nombre:

Para verificar si un contrato cumple las normas configurados en un ruleset simplemente se ejecutaría el siguiente comando indicando el conjunto de reglas a chequear y sobre qué contrato hacerlo:

Un ejemplo de verificacion correcto sería el siguiente:

Un ejemplo de verificación que no cumple algunas reglas sería el siguiente:

Como se muestra en la captura, la salida de la ejecución del error que devuelve Speccy indica cual es la regla que no se cumple.

En este caso:

Se pueden definir tantos rulesets como se deseen e incluir en ellos las normas que se necesite corroborar. Para hacerlo, simplemente hay que generar un fichero yaml que contenta las reglas a verificar siguiendo el siguiente formato para cada una de ellas:

Un posible ejemplo de norma no incluida en los rulesets por defecto, y que sería interesante incluir, por ejemplo, sería obligar a que se defina una descripción a nivel de método u operación quedando de la siguiente forma:

También es posible habilitar o deshabilitar una regla dentro de un ruleset o saltar una determinada regla mediante la línea de comandos con la opción --skip, seguido de la lista de reglas que no se quieren comprobar. Por ejemplo: --skip="contact-properties,license-url"

Una posible lista de reglas a incorporar en la verificación de un contrato y que no se incluyen por defecto serían:

Dentro de las ventajas de esta herramienta, además de la funcionalidad obvia que ofrece es que Speccy está disponible como un paquete de node, por lo que se puede ejecutar fácilmente en la línea de comandos y, al igual que ocurre con Newman, es fácilmente integrable en nuestro pipeline.

La desventaja de esta herramienta es que solo soporta versión OAS 3.0 no versión 2.0. Si se quiere ejecutar la revisión de calidad para definiciones de API en versión 2.0 es necesario incluir un paso previo que transforma la especificación de la versión 2.0 a 3.0, para lo cual podemos ayudarnos de la librería swagger2openapi.

Una posible idea para usar Speccy, además de incorporarlo a un pipeline de integración continua como en este caso, podría ser ofrecer las reglas configuradas en Speccy con una API que las recubra por encima para poder gestionar dichas reglas de una manera sencilla e integrable en diferentes puntos del ciclo de vida de los proyectos, ya que muchas de estas reglas son reutilizables y son agnósticas del proyecto en sí.

Una propuesta de pipeline

Nuestra propuesta consiste en incorporar las herramientas anteriores en diferentes stages del pipeline de Jenkins, que se ejecutará al incluir/cambiar una funcionalidad mediante una Pull Request al repositorio.

En dicho repositorio Git se almacenarán los siguientes archivos: contrato de la API OAS 2.0 o 3.0, colección Postman con los tests y los ficheros de las variables de entorno. En el momento en el que se suba un cambio mediante una Pull Request el flujo realiza los siguientes pasos:

Siguientes pasos

Este pipeline es solo una propuesta sujeto a mejoras y cambios según los objetivos que se marquen conseguir. Como posibles mejoras a incorporar en el flujo se pueden citar las siguientes:

Referencias

Cuéntanos qué te parece.

Enviar.

Los comentarios serán moderados. Serán visibles si aportan un argumento constructivo. Si no estás de acuerdo con algún punto, por favor, muestra tus opiniones de manera educada.