¿Qué es OpenAPI?
Equipo editorial de IONOS
OpenAPI es un estándar para la descripción de las interfaces de programación, o application programming interfaces (API). La especificación OpenAPI define un formato de descripción abierto e independiente de los fabricantes para los servicios de API. En particular, OpenAPI puede utilizarse para describir, desarrollar, probar y documentar las API compatibles con REST.
La actual especificación OpenAPI surgió del proyecto predecesor Swagger. La empresa de desarrollo SmartBear sometió la especificación existente de Swagger a una licencia abierta y dejó el mantenimiento y desarrollo posterior en manos de la iniciativa OpenAPI. Además de SmartBear, entre los miembros de la iniciativa OpenAPI se encuentran gigantes de la industria como Google, IBM y Microsoft. La Fundación Linux también apoya este proyecto.
- Registros DNS
- Administración SSL
- Documentación API
OpenAPI de un vistazo
Una cuestión que puede causar confusión es la distinción entre OpenAPI y Swagger. OpenAPI es una especificación, es decir, una descripción abstracta que no está ligada a una aplicación técnica concreta. Hasta la versión 2.0, esta especificación todavía se llamaba Swagger y luego fue renombrada como especificación OpenAPI. Sin embargo, las herramientas proporcionadas por SmartBear, la empresa que la desarrolló originalmente, siguen existiendo con el nombre de Swagger.
Con OpenAPI, una API puede describirse de manera uniforme. Esto se conoce como “definición API” y se genera en un formato legible por máquina. En particular, se utilizan dos lenguajes: YAML y JSON.
Aparte de la definición API, a veces se emplea el término “especificación API”. Se trata de una descripción abstracta de una API creada exclusivamente para el espectador humano.
Técnicamente, YAML y JSON difieren solo ligeramente, por lo que es posible convertir automáticamente una definición API existente de un lenguaje a otro. Sin embargo, YAML tiene una estructura más clara y es más fácil de leer para las personas. A continuación, un ejemplo del mismo objeto del servidor OpenAPI, presentado en YAML y JSON:
# YAML
servers:
- url: https://development.example.com/v1
description: Development server
- url: https://staging.example.com/v1
description: Staging server
- url: https://api.example.com/v1
description: Production server// JSON
{
"servers": [
{
"url": "https://development.example.com/v1",
"description": "Development server"
},
{
"url": "https://staging.example.com/v1",
"description": "Staging server"
},
{
"url": "https://api.example.com/v1",
"description": "Production server"
}
]
}La especificación OpenAPI define una serie de propiedades que pueden utilizarse para desarrollar una API propia. Estas propiedades se agrupan en los llamados objetos (en inglés, objects). En la actual versión 3.0.3, OpenAPI define la estructura de los siguientes objetos, entre otros:
- Info Object: versión, nombre, etc. de la API.
- Contact Object: datos de contacto del proveedor de la API.
- License Object: licencia bajo la cual la API proporciona sus datos.
- Server Object: nombres del host, estructura del URL y puertos del servidor a través del cual se dirige la API.
- Components Object: componentes encapsulados que pueden utilizarse varias veces dentro de una definición de API.
- Paths Object: rutas relativas a los puntos finales de la API que se utilizan junto con el servidor del objeto.
- Path Item Object: operaciones permitidas para una ruta específica como GET, PUT, POST, DELETE.
- Operation Object: especifica, entre otras cosas, los parámetros y las respuestas del servidor que se esperan de una operación.
¿Cuáles son las áreas de aplicación de OpenAPI?
En general, OpenAPI se utiliza para describir API REST de manera uniforme. Como esta descripción, es decir, la definición API, está disponible en un formato legible por máquina, se pueden generar automáticamente diversos artefactos virtuales a partir de ella. En concreto, estos incluyen:
- Creación de documentación API: La documentación basada en HTML se genera automáticamente a partir de la definición API legible por máquina. Esta sirve como material de consulta para los desarrolladores que acceden a los servicios API. Si la definición API cambia, la documentación se vuelve a generar para que ambas concuerden.
- Creación de conexiones en diferentes lenguajes de programación: Con las herramientas apropiadas, se puede crear una biblioteca de software adecuada del lado del cliente a partir de la definición API en un lenguaje de programación compatible. Esto permite a los programadores de todo tipo acceder a la API. La biblioteca de software se incorpora de manera convencional. Por lo tanto, el acceso a los servicios de API tiene lugar, por ejemplo, mediante el acceso a las funciones dentro del mismo entorno de programación.
- Elaboración de casos de prueba: Cada componente de un software debe someterse a diversas pruebas para asegurar su funcionalidad. En concreto, es preciso volver a probar un componente de software cada vez que se cambia el código subyacente. A partir de la definición API, se pueden generar estos casos de prueba automáticamente para poder comprobar la funcionalidad de los componentes del software en todo momento.
En última instancia, cabe señalar que no todas las API pueden representarse utilizando OpenAPI. Sin embargo, las API REST son compatibles sin duda.
¿Qué ventajas tiene OpenAPI?
En general, la ventaja de OpenAPI es que la puesta en marcha, documentación y prueba de una API son coherentes y constantes durante el desarrollo y el mantenimiento. Además, el uso de la especificación OpenAPI permite una mejor coordinación del desarrollo de la API entre los equipos de backend y frontend. En ambos equipos, los componentes del código pueden generarse a partir de la definición API para que tanto en backend como en frontend puedan desarrollarlos y probarlos sin tener que esperar al otro.
Además de estas ventajas generales, OpenAPI se utiliza en particular como estándar de base para el desarrollo de API REST. Esto es atractivo, porque desarrollar una API compatible con REST de forma manual no es una trivialidad. Sin embargo, las API REST ofrecen algunas ventajas. Por ejemplo, REST se ejecuta sobre HTTP/S, y los puertos para ello están abiertos en cualquier cortafuegos.
Además, el uso de OpenAPI ofrece las siguientes ventajas:
- Definir las API HTTP independientemente de un lenguaje de programación específico.
- Generar código de servidor para una API definida en OpenAPI.
- Generar bibliotecas del lado del cliente para una API compatible con OpenAPI en más de 40 lenguajes de programación.
- Procesar una definición OpenAPI con las herramientas apropiadas.
- Crear documentación interactiva de API.
- Permitir que las personas y las máquinas descubran y entiendan las capacidades de un servicio sin tener que mirar el código fuente o la documentación adicional.
- Acceder a los servicios de API con un gasto mínimo de puesta en marcha.
¿Qué versiones de OpenAPI están disponibles y en qué se diferencian?
En el momento de la redacción de este artículo, la versión 3.0.3 de OpenAPI es la más actualizada. A continuación, presentamos un breve resumen de las versiones anteriores:
| Versión | Nombre | Estado |
|---|---|---|
| 1.0, agosto de 2011 | Especificación Swagger | No está en uso |
| 2.0, septiembre de 2014 | Especificación Swagger > especificación OpenAPI | Todavía en uso |
| 3.0, julio de 2017 | Especificación OpenAPI | Todavía en uso |
A continuación, se exponen las novedades más importantes del cambio de la versión 2.0 a la 3.0:
Nuevo nombre del objeto raíz
Con el lanzamiento de la versión 3.0, se introdujo el objeto OpenAPI, que sustituye el objeto Swagger utilizado anteriormente:
# <= 2.0
"swagger": "2.0"
# >= 3.0
"OpenAPI": "3.0.0"Múltiples hosts/servidores
A partir de la versión 3.0 de OpenAPI, se puede acceder a una API desde más de un servidor. Además, es posible definir partes del URL del servidor de forma variable. A continuación, mostramos un ejemplo:
"servers": [
{
"url": "https://{username}.example.com:{port}/{basePath}",
"description": "The production API server",
"variables": {
"username": {
"default": "demo",
"description": "this value is assigned by the service provider, in this example `example.com`"
},
"port": {
"enum": [
"8443",
"443"
],
"default": "8443"
},
"basePath": {
"default": "v2"
}
}
}
]Nuevos objetos componente y objetos referencia
Los objetos componente y objetos referencia añadidos en la versión 3.0 de OpenAPI son una de las principales novedades. El objeto componente permite definir múltiples objetos reutilizables dentro de la definición API. Los componentes denominados de esta manera se incluyen dentro de la definición API usando la estructura especial $ref.
Mediante los componentes y referencias, es posible elaborar una definición API a partir de varias partes reutilizables. Esto facilita la lectura y reduce el tamaño de todo el documento. A continuación, presentamos un ejemplo de la definición oficial de API de GitHub:
- Esquema de un repositorio de código GitHub, definido como un objeto componente.
- Definición de licencia, referida a través de un componente definido externamente.
"components": {
"schemas": {
// Esquema Repository
"repository": {
"title": "Repository",
"description": "A git repository",
"type": "object",
"properties": {
"id": {
"description": "Unique identifier of the repository",
"example": 42,
"type": "integer"
},
"node_id": {
"type": "string",
"example": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5"
},
"name": {
"description": "The name of the repository.",
"type": "string",
"example": "Team Environment"
},
"full_name": {
"type": "string",
"example": "octocat/Hello-World"
},
// Definición de licencia
"license": {
"nullable": true,
"allOf": [
{
// Referencia a componente definido externamente
"$ref": "#/components/schemas/license-simple"
}
]
},Uso de OpenAPI: dos ejemplos
La especificación OpenAPI y sus herramientas correspondientes, en particular Swagger, se utilizan con frecuencia para crear diversas API. A continuación, presentamos dos ejemplos:
API REST v3 de GitHub
El popular servicio de Git GitHub utiliza OpenAPI para describir su “API REST v3 de GitHub”. La definición de API está disponible en GitHub como un repositorio. Con su ayuda, un usuario puede determinar con exactitud a qué servicios se puede acceder a través de la API de GitHub y cómo deben estructurarse exactamente las solicitudes entrantes. Además, cualquiera puede utilizar la API para generar el código adecuado utilizando las herramientas apropiadas.
Según GitHub, la definición API se utiliza para describir, crear, consumir y visualizar API REST. En el momento de redactar este artículo, la definición API no está completa. Por una parte, algunos encabezados faltan aún y se añadirán en el futuro. También se observa que algunas de las posibles operaciones de API pueden realizarse a través de diferentes rutas, aunque en la especificación solo se incluye una ruta.
Por razones de compatibilidad, GitHub ofrece la definición API en diferentes formatos. Por un lado, hay una versión llamada “empaquetada” (bundled), que contiene los componentes introducidos con OpenAPI 3.0 y las referencias a los mismos. Como contrapartida, se ofrece una versión denominada “desreferenciada” (dereferenced) en la que se resuelven todas las referencias. Debido a la redundancia que implica, la definición de API desreferenciada es tres veces más grande que la empaquetada. Muchas herramientas no admiten todavía referencias. Para estos casos, la definición de API desreferenciada es una buena opción.
Puedes echar un vistazo a la definición API tú mismo. Ten en cuenta que el archivo completo tiene un tamaño de varios megabytes. Para un archivo de texto, esta cantidad de información es extremadamente grande. GitHub no puede mostrar directamente un archivo tan voluminoso. Sin embargo, puedes utilizar el siguiente enlace para ver el GitHub API REST en el navegador. Esta es la versión en YAML, mucho más compacta y legible: GitHub API REST (YAML).
Ejemplo de una tienda de mascotas con SwaggerHub
En segundo lugar, mostramos un ejemplo de API que puede crearse en SwaggerHub. SwaggerHub es una plataforma online para diseñar y desarrollar API REST con OpenAPI. Puedes crear una cuenta de usuario gratuita en esa plataforma, aunque también puedes registrarte con una cuenta existente en GitHub.
Una vez hayas accedido a SwaggerHub, puedes crear una nueva API. Existe una opción que permite comenzar sobre una plantilla existente. Por ejemplo, hay una plantilla de API para una “Petstore” virtual, es decir, para una tienda de mascotas. La API de Petstore creada con la plantilla incluye una amplia gama de objetos OpenAPI. Entre otros, se encuentran los siguientes:
- Datos de contacto, condiciones de uso, licencia, etc.
- Endpoints de API y las operaciones de cada endpoint.
- Parámetros de entrada y salida permitidos de las operaciones.
- Especificaciones de seguridad.
Si observas la API de Petstore, puedes aprender mucho acerca de cómo funciona OpenAPI. Además, la definición de Petstore es un buen ejemplo de cómo desarrollar una API de acuerdo con REST. Para finalizar, vamos a poner un ejemplo de código de la API de Petstore. Analizamos la sección del código que aparece a continuación:
- El código define el endpoint de API/pet.
- Con una solicitud HTTP POST, se añade una nueva mascota a la tienda de mascotas.
- Si, en su lugar, utilizas el verbo HTTP PUT en el mismo endpoint, puedes modificar una mascota existente.
- Se definen varias respuestas del servidor para las operaciones. En este ejemplo, los códigos de estado HTTP definidos para ello incluyen el conocido código de estado 404 “No encontrado”. En el caso de la API de Petstore, la expresión se transforma en “Mascota no encontrada”.
Las líneas de código que comienzan con $ref y llevan el comentario de “OpenAPI 3.0+ Component” son referencias a componentes OpenAPI definidos individualmente.
# Petstore API Template #
# API Endpoint '/pet'
/pet:
# HTTP-POST Request
post:
tags:
- pet
summary: Add a new pet to the store
operationId: addPet
# HTTP-Status codes
responses:
'405':
description: Invalid input
security:
# Permissions
- petstore_auth:
- 'write:pets'
- 'read:pets'
requestBody:
# OpenAPI 3.0+ Component
$ref: '#/components/requestBodies/Pet'
# HTTP-PUT Request
put:
tags:
- pet
summary: Update an existing pet
operationId: updatePet
# HTTP-Status codes
responses:
'400':
description: Invalid ID supplied
'404':
description: Pet not found
'405':
description: Validation exception
security:
# Permissions
- petstore_auth:
- 'write:pets'
- 'read:pets'
requestBody:
# OpenAPI 3.0+ Component
$ref: '#/components/requestBodies/Pet'OpenAPI se ha establecido como un formato de descripción abierto e independiente de los fabricantes para los servicios de API. Se espera que OpenAPI se utilice ampliamente como estándar para el desarrollo de API REST en un futuro próximo.
