Skip to main content

Es Necesario Saber

OpenAPI

Sitio OpenAPI

Github OpenAPI

OpenAPI es una especificación abierta y estandarizada para describir APIs RESTful, que surgió a partir del Swagger desarrollado por SmartBear. En 2015, se creó la OpenAPI Initiative (OAI) bajo la Linux Foundation, y Swagger Specification fue donado a OAI, convirtiéndose en la base de lo que hoy conocemos como OpenAPI Specification (OAS). Desde entonces, OpenAPI ha evolucionado como el principal estándar para describir APIs RESTful.

En algún momento de tu carrera te encontrarás con la necesidad de entender mejor sobre APIs.

Las APIs (Application Programming Interfaces) son interfaces que permiten la comunicación entre diferentes sistemas, software o componentes de un software. Definen reglas y protocolos que permiten que un sistema acceda a funcionalidades o datos de otro de manera estructurada y segura.

Podríamos comparar una API con un menú de restaurante:

  • El menú muestra lo que está disponible (servicios o datos que el sistema ofrece).
  • Tú (el cliente) haces un pedido basado en el menú (la solicitud a la API).
  • La cocina (el sistema de backend) procesa tu pedido y devuelve el plato (el resultado) sin que necesites saber cómo fue preparado.

Existen varios tipos de APIs siendo la más usada lo que llamamos APIs RESTful que está basada en el protocolo HTTP y sigue el estilo arquitectural REST (usando métodos como GET, POST, PUT, DELETE, etc).

OpenAPI y las APIs RESTful están conectados porque OpenAPI es una especificación que describe cómo debe funcionar una API RESTful. Proporciona un estándar para documentar y estructurar APIs RESTful, haciéndolas más fáciles de entender, implementar y consumir.

alt text

La especificación por sí sola ya tiene mucho valor y puede ser consumida por diferentes herramientas y procesos, haciéndola útil incluso sin una interfaz visual. La UI es un complemento que mejora la experiencia de los desarrolladores, pero no es un requisito para usar OpenAPI. A través de esta UI podemos tener ejemplos como estos e incluso podemos probar en el botón Try It Out.

alt text

Es necesario mitigar riesgos sobre exponer esta documentación públicamente, pues atacantes pueden explotar los endpoints e intentar diferentes tipos de ataques. Más adelante entenderemos cómo mitigar estos riesgos.

OpenAPI vs APIs RESTful​

  • APIs RESTful: Son un estilo arquitectural para construir APIs que utilizan el protocolo HTTP y estándares como:

    • Recursos representados por URLs (ej., /users, /orders).
    • Métodos HTTP como GET, POST, PUT, DELETE para operaciones CRUD.
    • Datos en formatos como JSON o XML.

  • OpenAPI: Es una especificación usada para describir APIs RESTful. Define:

    • Los endpoints disponibles.
    • Los métodos HTTP soportados.
    • Los parámetros que pueden ser enviados (query, path, headers, body).
    • Los tipos de datos esperados (ej., JSON, XML).
    • Las respuestas devueltas (códigos de estado y estructura del payload).

Beneficios de OpenAPI para APIs RESTful​

  • Documentación automática: Herramientas como Swagger UI pueden generar documentación interactiva basada en archivos OpenAPI.
  • Estandarización: Define un formato claro y consistente para diseñar APIs.
  • Validación: Las herramientas pueden validar si una API está adhiriendo a la especificación definida.
  • Mock APIs: Permite crear versiones falsas de la API para desarrollo antes de la implementación real.
  • Generadores de código: Puede generar clientes y servidores automáticamente en varios lenguajes.
  • Ampliamente utilizado en API Gateways: La mayoría de los API Gateways utilizan archivos que definen la API con una configuración OpenAPI.
  • Agnóstico: No está creado para ninguna tecnología y lenguaje específico.
  • Soporte: Apoyado por varios grandes jugadores del mercado. Biblioteca disponible en prácticamente todos los lenguajes.

OpenAPI es considerado el estándar para describir APIs.

OpenAPI 2.0 vs 3.0​

La diferencia entre OpenAPI 2.0 y OpenAPI 3.0 está en mejoras significativas en la funcionalidad, flexibilidad, y en la manera como los recursos de APIs son descritos, por lo que el SCHEMA fue cambiado y debemos estar atentos a esto. El principal cambio fue hacer los componentes más reutilizables, estandarizados y fáciles de definir.

alt text

Vamos a enfocarnos en el estudio ya en la 3.0 siendo que este es el futuro.

OpenAPI en el IDE​

La especificación está escrita en archivos YAML o JSON. Para ayudar a escribir estas especificaciones y respetar el SCHEMA tenemos plugins en los IDEs que facilitan bastante. A veces nos traen templates listos para rellenar. Particularmente utilizar YAML facilita bastante la lectura además de ser menos verboso.

Por ejemplo tenemos en VSCode este plugin.

alt text

Una vez instalado ya lo tenemos apareciendo al lado y cuando pedimos crear un template ya vendrá listo ayudándonos inclusive con un explorador al lado dividiendo las sesiones.

alt text

Entonces no es necesario sufrir tanto así, incluso podemos ver cómo queda la UI.

Herramientas OpenAPI​

Existen varias herramientas que ayudan en el desarrollo:

  • Convertidores
  • Validadores
  • Editores
  • Mock Services
  • Generadores de SDK
  • Documentación.

Una lista de herramientas conocidas puede ser encontrada en https://tools.openapis.org/.

alt text

Swagger Hub​

Ya vimos que podemos usar solamente plugins dentro del IDE que nos ayuden a especificar, pero antes es bueno saber que SmartBear, que hizo la donación de Swagger a la iniciativa OpenAPI, posee diversas herramientas comerciales y open source que facilitan en el desarrollo de APIs a través del Swagger Hub.

Para aprender, si va a facilitar tu vida, puedes hacer una cuenta gratuita solamente para ti, una vez que es gratis solamente para 1 persona. Swagger Hub tiene un conjunto de herramientas incluyendo un editor.