Publicación APIs

He estado revisando un poco el tema de cómo hacen los grandes para publicar sus APIs, y por lo que veo no hay una regla más o menos común.

Por lo que parece cada uno tiene su método para publicar sus APIs públicas en la web de una forma más o menos automatizada, de tal forma, que se genera un contenido estático que se puede consultar como referencia, supongo que bien a partir de unos ficheros de definición del API, o a partir del propio código.

Por ejemplo, uno de los APIs más extensamente documentados es el API REST de cloudfare:

• API REST CLOUDFARE

https://api.cloudflare.com/

Todo el API viene documentado con ejemplos de solicitudes y respuestas, y las solicitudes vienen agrupadas por categorías. Lo que veo también es que las APIs van mutando conforme a sus necesidades, por lo que el servidor de APIs suele mantener las URLs antiguas, y las solicitudes se realizan siempre sobre una URL que dentro del árbol contiene la versión del API.

En el caso de cloudfare se ve que el proceso de publicación, si bien es automatizado, contiene texto explicativo para cada llamada así como ejemplos, lo que lleva a suponer que igual se genera automáticamente a partir de la documentación contenida dentro del propio código que la soporta.

• API KUBERNETES

Otro de los ejemplos de APIs REST extensamente documentados en la web es el API de Kubernetes:

https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.9/

La documentación de este API, como su propio nombre dice en la URL, está «generado». Escarbando un poco más vemos que utiliza el swagger para definir y documentar las APIs:

https://kubernetes.io/docs/concepts/overview/kubernetes-api/

Según comenta en el link de arriba, las APIs son documentadas y expuestas directamente a través del servidor de APIs utilizando los documentos de especificación openAPI con el swagger. Se da la circunstancia de que kubernetes facilita herramientas al administrador del sistema que permiten generar y modificar APIs adhoc para gestionar su plataforma de contenedores a medida. Dichas APIs se generan por linea de comando y almacenan de forma serializada en el servidor de APIs para poder ser publicadas y expuestas por el servidor conforme se van generando y/o modificando. Hay otro link en un foro que habla sobre el tema aquí:

https://thenewstack.io/taking-kubernetes-api-spin/

• APIS GENERADAS SOLUCION SPRING BOOT

En otro link se comenta una solución para publicar en base a los ficheros openAPI las APIs generadas para una solución de software llamada spring boot:

https://keyholesoftware.com/2017/03/28/auto-publishing-monitoring-apis-with-spring-boot/

Como curiosidad, el propio kubernetes utiliza un API alternativo basado en el protocol buffers desarrollado por google, y que utilizan extensivamente las plataformas de microservicios desplegadas bajo demanda en la nube. Aquí aparece la justificación de la migración del API al nuevo formato, por motivos de escalabilidad y simplicidad, principalmente.

https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/protobuf.md

En el caso de Go se utiliza una librería llamada gogo-protobuff mucho más eficiente a efectos de rendimiento en la serialización/deserialización que la librería nativa de google. Esta es la página del proyecto donde aparecen también algunas de las empresas que la usan, entre ellas Cloudfare:

https://github.com/gogo/protobuf

Como veis el tema de la optimización y gestión de APIs es un problema recurrente.

• DOCUMENTACION APIS POR GOOGLE

Este es el enfoque utilizado por Google para su API de gestión de cloud:

https://cloud.google.com/apis/design/proto3

https://developers.google.com/protocol-buffers/

Aquí tienen publicada en github las APIs, en un repositorio:

https://github.com/googleapis/googleapis

Los ficheros de entrada son los protobuff, y también ficheros YAML. Con esos ficheros utilizan una herramienta llamada Artman para generar y publicar las APIs:

https://github.com/googleapis/artman

Al generar y publicar las modificaciones de las APIs automáticamente mediante el repositorio GIT, utilizan una sistema de integración continua (en este caso en lugar de Travis utilizan Circle) para ver los resultados de las pruebas:

https://circleci.com/gh/googleapis/googleapis

Pues eso, que cada maestrillo tiene su librillo, pero la cosa se resume en que se utiliza un lenguaje para especificar los mensajes petición/respuesta del API, y este se compila tanto para generar las funciones de serialización/deserialización de los mensajes, como para publicarlo y hacerle las pruebas de regresión, etc… con el fin de que un cambio en la especificación no rompa nada en los servicios que están en producción. La apuesta de Google por la cosa esta es que tiene unos 48000 y pico mensajes en más de 12000 APIs para gestionar todos sus servicios internos, y mantener y escalar todo eso se convertía en un infierno, por eso hace unos 5 años empezaron a apostar por el proyecto y a migrar todo internamente al nuevo formato de encapsulación de datos. En este link aparece un poco de historia y explica bastante bien los motivos que les condujeron a adoptar esa solución:

https://developers.google.com/protocol-buffers/docs/overview

Como podéis ver la generación de los ficheros proto para los mensajes es bastante sencilla, y eso es precisamente lo que andaba buscando la gente de Google, enfocarse en la parte de la lógica del microservicio y dejar a la capa de transporte en un plano aparte con un problema resuelto.

Aplicado al caso práctico con el swagger: supongo que si el kubernetes tiene la posibilidad de publicar en el servidor de APIs los ficheros openAPI generados usando el swagger, debe de haber alguna forma de mantener en un repositorio git los ficheros YAML o JSON con las especificaciones openAPI, y en el swagger configurar el directorio con la versión actualizada de los ficheros del repo para poder publicarlo directamente a través del puerto.

Es decir, que haces un commit sobre el repositorio git, y se lanza un webhook (o periódicamente por crontab) un proceso para clonar la ultima versión de las APIs sobre el directorio del que se alimenta el swagger para publicar las APIs. El tema de probar las APIs ya es cosa de hacerlo en un servidor de integración continua sobre un entorno de pruebas y publicar los resultados.