API

Publicación APIs

  • admin 

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.

Documentando APIs

  • admin 

DOCUMENTANDO APIs

Filón de herramientas que generan la documentación automáticamente en la web de las APIs generadas a partir de los ficheros OpenAPI.

Voy poniendo todas las que he encontrado, porque son unas cuantas y el resultado es cuestión de gustos.

La que veo más avanzada en cuestión de actualizaciones y contribuyentes es Redoc:

https://apis.guru/blog/redoc-release/

https://swagger.io/blog/redoc-openapi-powered-documentation/

https://github.com/Rebilly/ReDoc/

Pero no es la única existente, y hay otros proyectos que tampoco tienen mala pinta, como Spectacle:

https://github.com/sourcey/spectacle

O DapperDox (este está hecho en golang ;-)):

http://dapperdox.io/

https://github.com/DapperDox/dapperdox

Por cierto, el propio Swagger tiene su sistema de generación de documentación, pero por lo que se ve en los blogs todo el mundo coincide que el Swagger es más indicado para editar y validar los ficheros OpenAPI (es decir, es una herramienta más orientada para trabajar en la parte de definición de los APIs), que para generar la documentación, al menos no de la forma tan extensa en que lo hacen las herramientas anteriores:

http://idratherbewriting.com/learnapidoc/pubapis_swagger.html

https://github.com/swagger-api/swagger-ui

Por ultimo, os dejo un enlace de un blog donde hace un repaso a bastantes herramientas de documentación de APIs, no solo de OpenAPI. Lo he encontrado después de haber encontrado los proyectos anteriores, pero lo veo bastante completo por si queréis explorar otras herramientas:

https://pronovix.com/blog/free-and-open-source-api-documentation-tools

Por cierto, los de APIs.guru son expertos en la publicación y análisis de APIs (son los creadores de Redoc) en un sistema llamado GraphQL (aparte del OpenAPI) y tienen varios proyectos sorprendentes para sacarle el máximo partido a esta forma de trabajar con modelos de datos:

https://apis.guru/

http://graphql.org/

El GraphQL lo usan para sus aplicaciones móviles la gente de Facebook, por ejemplo. Uno de los proyectos sobre GraphQL que han desarrollado los de APIs.guru es un navegador de GraphQL:

https://github.com/APIs-guru/graphql-voyager

La demo que tienen sobre varios APIs (incluido el de GitHub) es impresionante. Merece la pena echarle un vistazo para darse cuenta del potencial que tiene (p.e. elegid el esquema de GitHub y uno de los nodos raíces):

https://apis.guru/graphql-voyager/