¿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 utilizar esta API, incluidos los endpoints 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 de contrato (en esencia, describe lo que debe hacer una API; no es jurídicamente vinculante) entre los usuarios y los proveedores de la API. Básicamente 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 tanto a humanos como a ordenadores comprender 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 parte del trabajo de documentación repetitivo 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 de los desarrolladores.

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 a la API reales, 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 integral de API, que respalde la integración, la colaboración, la prevención de errores y una gestión de API más sólida.

La especificación completa se puede encontrar en GitHub.

Como estándar de facto del sector, OpenAPI ofrece un documento seguro, automatizado y ampliamente aceptado para el desarrollo de API.

OpenAPI fue creado originalmente por el desarrollador Tony Tam y lanzado por primera vez en 2011 bajo el nombre Swagger. En aquella época, las especificaciones de API solían ser documentos estáticos que requerían una actualización tediosa y que a menudo estaban desactualizados. La especificación Swagger incluía varias innovaciones en el desarrollo de API, entre ellas un botón de "probar" para comprobar las llamadas a la API en directo y en tiempo real.

Swagger hizo de la documentación el eje central de su razón de ser. Permitía 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, garantizando así 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: independientemente del lenguaje utilizado en el backend, Swagger generaba un archivo JSON universal.

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 paraguas de la Fundación Linux. 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 incluir los camposopenAPI yinfo , y al menos un campopath , component o webhook. ¹

openAPI: indica 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, una descripción de la API, las condiciones del servicio e información de contacto. 

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

paths: describe las rutas y los métodos HTTP asociados (u operaciones, como GET, PUT, POST) y los parámetros, cuerpos de solicitud y respuestas para cada elemento de la 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 referencian, de forma sencilla, con $ref. Esta estrategia mantiene el diseño de una API lo más ágil posible. 

Seguridad: indica los esquemas de seguridad y los mecanismos de autenticación que utiliza la API, como OAuth o las claves de API. También permite la aplicación de esquemas de seguridad de forma 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" o "Pedidos").

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

webhooks: describe las llamadas entrantes que recibe la API. 

OpenAPI proporciona una única fuente fiable para desarrolladores y consumidores de API, y proporciona características que añaden valor y eficiencia a los proyectos de API.

OpenAPI se creó inicialmente con un enfoque claro en la documentación de las API REST, y ese enfoque sigue siendo su esencia hoy en día. La documentación está estandarizada, es interactiva, se actualiza en tiempo real y constituye una única fuente fiable.

Existen varias herramientas para leer documentos de OpenAPI y exportar código. Una de esas herramientas es Swagger Codegen, que lee documentos escritos según 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 son legibles por humanos.

Una de las características más innovadoras de OpenAPI sigue siendo el botón "probar", que permite realizar pruebas y validaciones en tiempo real directamente desde el navegador. Swagger UI, 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 inmediata del correcto funcionamiento de una solicitud.

OpenAPI se utiliza 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 OpenAPI que describen sus API, las plataformas iPaaS pueden utilizar esta información para descubrir automáticamente endpoints, métodos de autenticación y estructuras de datos. Esta estrategia agiliza la creación de integraciones, como la conexión de 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. El trabajo paralelo es preferible a que, como ocurre a veces, el equipo de interfaz se vea obligado a esperar hasta que el equipo de backend tenga su base de datos en funcionamiento. Con un contrato OpenAPI, el equipo frontend puede crear un servidor API simulado que se comporta como uno real, lo que permite y optimiza las pruebas antes de que se complete el desarrollo del backend. 

El gobierno de las API (es decir, las normas, políticas y prácticas que rigen la forma en que una organización desarrolla y utiliza las API) es fundamental para garantizar que estas funcionen de manera fluida, coherente y sin repeticiones innecesarias. Dado que OpenAPI actúa como un contrato entre desarrolladores, el gobierno y la seguridad pueden integrarse desde el principio.

Tomemos como ejemplo las pasarelas API, que se encargan de tareas como el enrutamiento del tráfico, la monitorización y la limitación de velocidad. Las pasarelas API suelen consumir especificaciones 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 OpenAPI permite a los desarrolladores definir requisitos de seguridad (como el uso de OAuth 2.0 o claves de API), y estos requisitos pueden aplicarse en las etapas posteriores (por ejemplo, mediante una pasarela).  Describir las características de seguridad en un contrato de API ayuda a garantizar que los desarrolladores no instituyan esquemas de seguridad no compatibles.

OpenAPI puede mejorar la gestión de API (el proceso escalable de crear, publicar y gestionar conexiones de API) de varias maneras. Por ejemplo, dado 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 creen API duplicadas sin saberlo.

OpenAPI también admite una gestión y un gobierno coherentes al hacer que los estándares de la organización sean explícitos y aplicables. Los equipos pueden definir requisitos, como convenciones de versiones, formatos de respuesta a errores o patrones de nomenclatura, directamente en o junto a la especificación. Dado que estas expectativas están documentadas en un formato estandarizado, pueden validarse automáticamente con las nuevas API a medida que se añaden. 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 el portfolio de una organización.