Breaking

Post Top Ad

Your Ad Spot

sábado, 25 de enero de 2020

AsyncAPI vs OpenAPI: ¿Cuál es la diferencia?

El mundo de las API es a menudo uno de estándares, intereses y soluciones en competencia. Si bien tendemos a hablar sobre el espacio API como una comunidad cohesionada, la realidad es que las API en Internet abarcan algo más universal.
En el espacio de documentación de API , esto finalmente se reduce a una cuestión de consumo. ¿Quién está realmente usando la documentación? ¿Para qué sirve esa documentación? ¿Cómo impulsa el producto y aumenta su valor?
Hoy en día, vamos a buscar soluciones de documentación para los dos muy grandes tipos de API: API abierta y AsyncAPI . Ambas soluciones generan documentación legible por máquina, un concepto que discutiremos en breve, pero lo hacen para diferentes tipos de API.

¿Por qué documentar?

La documentación es universal para proyectos técnicos. Tanto es así que a menudo se considera tan importante como el código en sí. La documentación de la API es esencialmente una biblia de consumo, utilización y contextualización: sirve no solo para informar al usuario final, sino también para contextualizar y explicar esa información para que sea útil para alguna aplicación.
Hay dos tipos principales de documentación. La documentación legible por humanos  informa al usuario final y explica la información en un método que puede ser fácilmente consumido por un ser humano. Esta es la forma de documentación con la que la mayoría de las personas probablemente estén familiarizadas. Dicha documentación no es únicamente técnica. A menudo vemos manuales de usuario y otra documentación de ayuda en productos minoristas comunes, descargas de software, etc.
El tipo opuesto de documentación es legible por máquina . Como su nombre lo indica, solo se ocupa de proporcionar documentación técnica que las máquinas puedan analizar, comprender y utilizar. A diferencia de la documentación legible por humanos , que se utiliza principalmente para la comprensión y referencia de nivel base, la documentación legible por máquina a menudo se utiliza para ingerir y producir un subproducto o integración. Esta documentación se puede utilizar para desarrollar nuevas herramientas , generar nuevos datos o incluso desarrollar capas de compatibilidad para facilitar una mejor comunicación entre API.
Como se indicó anteriormente, ambas soluciones a continuación son legibles por máquina. Sin embargo, lo que documentan específicamente es dónde vemos divergencia.
Lea también:  Guía definitiva para más de 30 soluciones de documentación API

OpenAPI

Especificación OpenAPI
La especificación OpenAPI se puede usar para asegurar y acelerar el ciclo de vida de la API.
La especificación OpenAPI , conocida anteriormente como Swagger, es una solución que produce documentación legible por máquina para las API REST. Desarrollado inicialmente en 2010, Swagger fue adquirido posteriormente en 2015 por SmartBear Software. A medida que se desarrolló y expandió Swagger, se lanzó la Iniciativa Open API para desarrollar y promover aún más el conjunto de herramientas Swagger en un formato abierto, respaldado por los principales actores de la industria para garantizar la estandarización y el soporte. En 2016, Swagger fue renombrado oficialmente a la especificación OpenAPI.
OpenAPI es independiente del lenguaje y se utiliza para generar automáticamente documentación para un amplio conjunto de funciones, métodos, parámetros, modelos y más. El principal punto de venta detrás de OpenAPI es que, al unificar y estandarizar la documentación de esta manera, las bibliotecas del cliente , el código fuente, los ejecutables y la documentación se sincronizan de forma nativa, ya que la documentación de la especificación se utiliza para generar la mayor parte del resto.
Agregue a esto la utilización de recursos declarativos, lo que significa que el usuario final no necesita tener ningún conocimiento de la implementación del servidor, los recursos, el acceso al código del servidor, etc. para comprender y consumir los servicios, y usted tiene Solución sólida para servicios web RESTful .
Relacionado:  ¿Qué debe considerar antes de la adopción de OpenAPI?

AsyncAPI

AsyncAPI  comenzó como un proyecto paralelo en Hitch (API Changelog), y luego fue fundado por Fran Méndez. Los desarrolladores de AsyncAPI identificaron la falta de herramientas en el espacio impulsado por mensajes y, cuando se les presentó un conjunto de herramientas inversamente abundante para las API HTTP, decidieron que faltaba una pieza de estandarización en las especificaciones de la documentación.
A partir de esta necesidad identificada, comenzaron a buscar una solución para los sistemas de especificación estandarizados basados ​​en mensajes. Formularon una "teoría de API", por así decirlo, esencialmente, con tantos tipos de API interactivos como servicios web RESTful , GraphQL y arquitecturas basadas en mensajes, AsyncAPI serviría como un lenguaje unificador común para los diversos formatos, protocolos y especificaciones. , lo que permite una comunicación estandarizada en el sistema basado en mensajes.
El soporte es aparentemente efectivo: mediante sus propios cálculos, suponiendo que crean herramientas para 6 lenguajes de programación, 4 formatos de esquema y 5 protocolos, podrían generar 120 combinaciones posibles en el espacio controlado por mensajes. Ese es un número significativo y uno que ciertamente ofrece la solución estandarizada que fue diseñada originalmente.
Para más información:  7 protocolos buenos para documentar con AsyncAPI

Las diferencias

En última instancia, las dos soluciones aquí cubren lados muy separados de la misma moneda. Las API REST tienen una función y un propósito específicos y, como tales, requieren sus propios métodos y enfoques de documentación. Las API REST tienen, entre otras, una gran solución en forma de OpenAPI, un conjunto de métodos de documentación estandarizados para habilitar herramientas e interactividad.
Sin embargo, las API basadas en mensajes son muy diferentes y necesitan su propia solución que cubra las advertencias y consideraciones intrínsecas a las arquitecturas basadas en mensajes. Para estas API, existe AsyncAPI , que hace funcionalmente lo mismo que OpenAPI, pero con un enfoque basado en mensajes. El lema de AsyncAPI lo dice mejor: “Las API REST tienen OpenAPI. La mensajería tiene AsyncAPI. "
Es muy importante comprender que, si bien las dos soluciones tienen mucho en común, también son muy divergentes. Sí, tanto OpenAPI como AsyncAPI permiten una mayor cantidad de cooperación y colaboración entre diferentes API documentadas, pero OpenAPI es una solución para REST, y AsyncAPI es una solución para arquitecturas basadas en mensajes. Son reinos completamente diferentes, a pesar de los nombres de sonido similar y los propósitos de sonido similar.

Conclusión

En última instancia, el problema aquí es uno que tiene más de nomenclatura que de función. AsyncAPI y OpenAPI suenan muy similares al oído, y debido a esto, tienden a colocarse en el mismo "cubo" intelectual. Sin embargo, esta es una forma pobre de ver las soluciones, ya que los propósitos divergentes pintan una imagen muy llamativa de diferente forma y función entre los dos.
En pocas palabras, adoptar AsyncAPI es una obviedad para las API basadas en mensajes, pero lo mismo puede decirse de OpenAPI para las API RESTful, y por el contrario, no hay ninguna razón para que AsyncAPI realmente aparezca en una conversación sobre las API RESTful, o para OpenAPI para ser discutido en el contexto de arquitecturas basadas en mensajes.
Esperamos que esto haya aclarado algunos conceptos erróneos en torno a estas dos soluciones. Háganos saber en los comentarios lo que piensa y si esto fue útil o no.

No hay comentarios.:

Publicar un comentario

Dejanos tu comentario para seguir mejorando!

Post Top Ad

Your Ad Spot

Páginas