¿Qué es OpenAPI?

Un archivo OpenAPI, también conocido como documento OpenAPI o especificación OpenAPI, permite a un desarrollador describir una API. Esta especificación también describe cómo usar esta API, incluidos los endpoint disponibles, los parámetros de operación, los métodos de autenticación y otra información. Estas especificaciones están escritas en YAML o JSON, y el esquema JSON se utiliza para describir los formatos de datos dentro de una API.

OpenAPI sirve tanto como documentación como contrato (en esencia, describe lo que una API debería hacer; no es legalmente vinculante) entre los usuarios y los proveedores de la API. Esencialmente sirve como “una fuente de verdad” que proporciona las instrucciones en un formato estandarizado.

Esta estandarización simplifica el consumo y la integración de API. Permite que tanto los humanos como las computadoras comprendan la función y la estructura de una API determinada sin acceso al código fuente ni necesidad de comprender el funcionamiento interno de la API. También permite a los desarrolladores trabajar con una API, independientemente del lenguaje en el que se haya escrito.

OpenAPI automatiza la documentación interactiva y actualizada, eliminando algunos trabajos de documentación repetitivos y ayudando a garantizar que la documentación permanezca actualizada. OpenAPI también permite la generación de código para los SDK del cliente y la generación de otro código repetitivo automáticamente a partir de la especificación, lo que reduce el error humano y minimiza aún más la carga de trabajo del desarrollador.

Las herramientas que utilizan especificaciones de OpenAPI, incluida SwaggerUI, pueden representar una especificación de API en una interfaz interactiva. Esta interfaz no solo ayuda a visualizar la especificación, sino que también permite llamadas reales a la API, directamente desde el navegador o el servicio web, con fines de prueba y validación.

Al estandarizar la forma en que se describen las API REST, OpenAPI ayuda a mejorar la interoperabilidad y las herramientas, y respalda las operaciones a lo largo del ciclo de vida de la API. Una especificación sólida y bien mantenida puede ser una herramienta fundamental para implementar una estrategia de API integral, que respalde la Integración, la colaboración, la prevención de errores y la gestión de API más sólida.

La especificación completa se puede encontrar en GitHub.

Como estándar de facto de la industria, OpenAPI proporciona un documento seguro, automatizado y ampliamente comprendido para el desarrollo de API.

OpenAPI fue creado originalmente por el desarrollador Tony Tam y se lanzó por primera vez en 2011 con el nombre de Swagger. En ese momento, las especificaciones de API eran a menudo documentos estáticos que requerían una actualización tediosa y con frecuencia estaban desactualizados. La especificación Swagger incluía varias innovaciones en el desarrollo de API, incluido un botón “probarlo” para probar las llamadas API en vivo y en tiempo real.

Swagger hizo de la documentación un foco de su existencia. Esto permitió a los desarrolladores incluir anotaciones, similares a una nota adhesiva, en su código fuente. Swagger podría leer estas anotaciones y actualizar la documentación automáticamente, lo que garantiza que la documentación se mantenga al día sin necesidad de realizar tareas de actualización tediosas y repetitivas. Swagger también introdujo un formato para describir las API en JSON legible por máquina, lo que lo hizo independiente del lenguaje: sin importar el lenguaje de un backend, Swagger produciría resultados JSON universales.

Swagger fue adquirida por SmartBear Software en 2015, pasó a llamarse OpenAPI poco después y se donó a la nueva Iniciativa OpenAPI (OAI), bajo el control de la Linux Foundation. La versión actual es OpenAPI 3.1.

La especificación OpenAPI es un documento estandarizado, legible por humanos y máquinas, que define la estructura y la sintaxis de la API. Todos los documentos de OpenAPI incluyen ciertos componentes y se ajustan a la misma estructura básica, pero algunas especificaciones contienen más información que otras. Como mínimo, una especificación debe incluiropenAPI yinfo campos, y al menos un campopath , component o webhook . ¹

OpenAPI: señala la versión de OpenAPI que utiliza el documento, como “3.1.1”

info: incluye metadatos generales de la API, como el título y el número de versión de la API, una descripción de la API, los términos del servicio y la información de contacto. 

servers: una lista de direcciones URL base a las que se puede acceder a la API (que pueden incluir entornos de producción y preparación). Esta lista incluye variables para hosts específicos del entorno.

paths: Describe las rutas y los métodos HTTP asociados (u operaciones, por ejemplo, GET, PUT, POST), así como los parámetros, los cuerpos de las solicitudes y las respuestas para cada elemento de ruta.

components: enumera objetos reutilizables, como esquemas de datos, parámetros, respuestas, encabezados y definiciones de seguridad. Se puede hacer referencia a estos objetos en todo el documento. Los componentes se mencionan, de manera bastante simple, con $ref. Esta estrategia mantiene el diseño de una API lo más optimizado posible. 

security: indica los esquemas de seguridad y los mecanismos de autenticación que utiliza la API, como OAuth o claves de API. También permite la aplicación de esquemas de seguridad a nivel global o por operación.

tags: lista general de etiquetas que se utilizan para organizar las operaciones. El uso de etiquetas puede ayudar a mejorar la claridad del documento (por ejemplo, “Usuarios” u “Pedidos”).

external documentation: enlaces a guías, documentos de introducción y otra documentación externa sobre la API

webhooks: describe las llamadas entrantes que recibe la API. 

OpenAPI proporciona una única fuente de información para los desarrolladores y consumidores de API, y proporciona características que agregan valor y eficiencia a los proyectos de API.

OpenAPI se creó inicialmente con un gran enfoque en la documentación de las API REST, y ese enfoque sigue siendo su núcleo en la actualidad. La documentación está estandarizada, es interactiva, se actualiza en tiempo real y ofrece un contrato con una única fuente de información.

Existen varias herramientas para leer documentos de OpenAPI y exportar código. Una de esas herramientas es Swagger Codegen, que lee documentos escritos de acuerdo con la especificación OpenAPI. Swagger Codegen puede producir kits de desarrollo de software (SDK) de código de cliente API, código del lado del servidor (stubs) y páginas web legibles con documentación actualizada que es legible por humanos.

Una de las características más innovadoras de OpenAPI sigue siendo el botón “probarlo”, que permite realizar pruebas y validación en tiempo real directamente desde un navegador. La interfaz de usuario (IU) de Swagger, una herramienta gratuita de código abierto, habilita una interfaz visual en la que un desarrollador puede enviar solicitudes reales para ayudar a garantizar que respondan como se desea. Esta herramienta facilita la verificación instantánea de que una solicitud funciona correctamente.

OpenAPI se usa comúnmente con plataformas de integración como servicio o iPaaS.

Las plataformas iPaaS utilizan especificaciones OpenAPI para comprender y conectar diferentes aplicaciones en un ecosistema de TI. Cuando las aplicaciones exponen especificaciones de OpenAPI que describen sus API, las plataformas iPaaS pueden usar esta información para descubrir automáticamente endpoints, métodos de autenticación y estructuras de datos. Esta estrategia permite crear integraciones más rápidamente, como por ejemplo, conectar una plataforma de comercio electrónico con un software de contabilidad.

OpenAPI también permite a los desarrolladores de frontend y backend trabajar en paralelo. Es preferible trabajar en paralelo a que, como ocurre a veces, el equipo de frontend se vea obligado a esperar a que el equipo de backend tenga la base de datos en funcionamiento. Con un contrato OpenAPI, el equipo de frontend puede crear un servidor API simulado que se comporta como uno real, habilitando y optimizando las pruebas antes de que se complete el desarrollo del backend. 

La gobernanza de las API (los estándares, políticas y prácticas que dirigen cómo una organización desarrolla y usa las API) es vital para garantizar que las API funcionen perfectamente, de forma coherente y sin repeticiones innecesarias. Debido a que OpenAPI actúa como un contrato entre desarrolladores, la gobernanza y la seguridad se pueden integrar desde el principio.

Tomemos como ejemplo las pasarelas de API, que gestionan tareas como el enrutamiento del tráfico, el monitoreo y la limitación de velocidad. Las pasarelas normalmente pueden consumir especificaciones de OpenAPI y aplicar cualquier límite de tráfico u otras medidas de seguridad establecidas en la especificación.

Lo mismo se aplica a las reglas de seguridad. Una especificación de OpenAPI permite a los desarrolladores declarar requisitos de seguridad (como el uso de claves OAuth 2.0 y API), y estos requisitos se pueden aplicar en sentido descendente (quizás mediante una pasarela).  Describir las características de seguridad en un contrato de API ayuda a garantizar que los desarrolladores no implementen esquemas de seguridad no compatibles.

OpenAPI puede fortalecer la gestión de API, el proceso escalable de crear, publicar y gestionar conexiones API, de varias maneras. Por ejemplo, debido a que las especificaciones de OpenAPI son legibles por máquina y están estandarizadas, el software de catálogo y portal puede indexarlas automáticamente. Esta estandarización hace que las API sean más fáciles de encontrar y comprender en toda la organización. Esta capacidad de descubrimiento ayuda a evitar que los equipos construyan API duplicadas sin saberlo.

OpenAPI también admite una gestión y gobernanza coherentes al hacer que los estándares organizacionales sean explícitos y aplicables. Los equipos pueden definir requisitos, como convenciones de versiones, formatos de respuesta de error o patrones de nomenclatura, directamente en la especificación o junto a ella. Debido a que estas expectativas están documentadas en un formato estandarizado, se pueden validar automáticamente con nuevas API a medida que se agregan. Esta validación reduce la dependencia de la revisión manual y ayuda a garantizar que las API sigan siendo coherentes a medida que crece la cartera de una organización.