¿Qué son los parámetros de OpenAPI? #
OpenAPI, antes conocida como Swagger, es una especificación de código abierto para definir y documentar API RESTful. Uno de los elementos fundamentales de una especificación OpenAPI es cómo gestiona los parámetros. Los parámetros son esenciales para que una API sea flexible y versátil, ya que definen las distintas entradas que un endpoint de la API puede aceptar para cumplir su función. En este artículo detallado veremos qué son los parámetros de OpenAPI, los distintos tipos de parámetros y cómo se utilizan dentro de un documento OpenAPI.
Comprender los parámetros de OpenAPI #
En el contexto de OpenAPI, los parámetros son las entradas que se envían junto con la solicitud a la API. Estas entradas pueden influir en el comportamiento del endpoint de la API. Los parámetros pueden ser parámetros de ruta, de consulta, de encabezado o del cuerpo de la solicitud. Entender estos distintos tipos de parámetros es crucial para diseñar una API robusta y flexible.
Parámetros de ruta #
Los parámetros de ruta forman parte de la propia URL y se utilizan para identificar recursos específicos. Por ejemplo, considera la siguiente URL:
/users/{userId}
Aquí, {userId} es un parámetro de ruta. Los parámetros de ruta son siempre obligatorios: deben incluirse en la URL para que el endpoint funcione correctamente. En un documento OpenAPI, los parámetros de ruta se definen de la siguiente manera:
paths:
/users/{userId}:
get:
summary: Get a user by ID
parameters:
- name: userId
in: path
required: true
schema:
type: string
responses:
'200':
description: A single user
content:
application/json:
schema:
$ref: '#/components/schemas/User'
En este ejemplo, el parámetro userId se define en la ruta y se marca como obligatorio.
Parámetros de consulta #
Los parámetros de consulta se añaden al final de la URL y son opcionales. Suelen utilizarse para filtrar, ordenar o paginar datos. Una URL de ejemplo con parámetros de consulta tiene este aspecto:
/users?sortBy=name&limit=10
En esta URL, sortBy y limit son parámetros de consulta. Los parámetros de consulta se definen en un documento OpenAPI de la siguiente manera:
paths:
/users:
get:
summary: List users with optional sorting and pagination
parameters:
- name: sortBy
in: query
required: false
schema:
type: string
enum:
- name
- date
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
responses:
'200':
description: A list of users
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
Aquí, tanto sortBy como limit son parámetros opcionales que se usan para modificar el comportamiento de la solicitud.
Parámetros de encabezado #
Los parámetros de encabezado se utilizan para proporcionar metadatos adicionales a la solicitud a la API. Estos parámetros son menos visibles que los de consulta o de ruta, pero pueden ser igual de importantes, por ejemplo, para enviar tokens de autenticación o especificar tipos de contenido. En una URL no se aprecian claramente los parámetros de encabezado, pero los encabezados podrían tener este aspecto:
Encabezados:
Authorization: Bearer<access-token>
Accept: application/json
En un documento OpenAPI, los parámetros de encabezado se definen de la siguiente manera:
paths:
/secured-resource:
get:
summary: Access a secured resource
parameters:
- name: Authorization
in: header
required: true
schema:
type: string
- name: Accept
in: header
required: false
schema:
type: string
default: application/json
responses:
'200':
description: A secured resource
content:
application/json:
schema:
$ref: '#/components/schemas/SecuredResource'
En este ejemplo, el encabezado Authorization es obligatorio para acceder al recurso protegido.
Parámetros del cuerpo de la solicitud #
Los parámetros del cuerpo de la solicitud se utilizan para enviar estructuras de datos complejas a la API. A diferencia de los parámetros de ruta o de consulta, que suelen emplearse para cadenas de texto o números simples, los parámetros del cuerpo de la solicitud son útiles para enviar objetos JSON, datos XML o incluso archivos. No es posible mostrar un ejemplo de parámetro del cuerpo de la solicitud en una URL, pero el cuerpo de la solicitud podría tener este aspecto:
{
"name": "John Doe",
"email": "john.doe@example.com"
}
En un documento OpenAPI, los parámetros del cuerpo de la solicitud se definen de la siguiente manera:
paths:
/users:
post:
summary: Create a new user
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NewUser'
responses:
'201':
description: User created
content:
application/json:
schema:
$ref: '#/components/schemas/User'
Aquí, el cuerpo de la solicitud se especifica mediante la propiedad requestBody, que incluye el esquema de los datos que espera la API.
Serialización de parámetros #
La serialización se refiere a cómo se formatean los parámetros en la solicitud HTTP. OpenAPI admite varios estilos de serialización de parámetros, necesarios al trabajar con estructuras de datos complejas. Estos son los principales estilos de serialización:
- Matrix: los parámetros se serializan como
;key=value. Ejemplo:/users;id=1;name=John - Label: los parámetros se serializan como
.value. Ejemplo:/users/.id=1 - Form: los parámetros se serializan como en los formularios HTML:
key=value. Ejemplo:/users?id=1&name=John - Simple: los parámetros se serializan de forma simple:
key=value. Ejemplo:/users?id=1 - SpaceDelimited: los valores se delimitan con espacios. Ejemplo:
/users?id=1 2 3 - PipeDelimited: los valores se delimitan con barras verticales. Ejemplo:
/users?id=1|2|3 - DeepObject: los objetos complejos se serializan en parámetros independientes. Ejemplo:
/users?id[name]=John&id[age]=30
Así se especifica la serialización en un documento OpenAPI:
paths:
/users:
get:
summary: List users with custom serialization
parameters:
- name: id
in: query
required: false
style: simple
schema:
type: array
items:
type: string
responses:
'200':
description: A list of users
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
En este ejemplo, el parámetro id utiliza el estilo de serialización simple para sus valores de arreglo (array).
Casos de uso comunes #
Comprender los parámetros de OpenAPI puede influir de forma significativa en la usabilidad y la funcionalidad de tu API. Estos son algunos casos de uso comunes:
Filtrado de resultados: usa parámetros de consulta para filtrar los resultados que devuelve una API. Por ejemplo,
/users?active=truepuede usarse para devolver solo los usuarios activos.Paginación: combina parámetros de consulta como
pageylimitpara paginar los resultados de la API. Ejemplo:/users?page=2&limit=20.Ordenación: usa parámetros de consulta para ordenar los datos. Ejemplo:
/users?sortBy=name&order=asc.Autenticación: envía los tokens de autenticación mediante parámetros de encabezado. Ejemplo:
Authorization: Bearer<access-token>.Envío de datos complejos: usa parámetros del cuerpo de la solicitud para enviar estructuras de datos complejas, como objetos JSON o archivos.
Conclusión #
Los parámetros de OpenAPI son componentes esenciales que definen cómo pueden interactuar los clientes con tu API. Permiten personalizarla y darle flexibilidad, de modo que la API pueda atender una amplia variedad de casos de uso. Comprender los parámetros de ruta, de consulta, de encabezado y del cuerpo de la solicitud, así como sus estilos de serialización, es fundamental para crear una especificación de API robusta.
Para profundizar y consultar más recursos sobre OpenAPI, puedes acudir a la especificación OpenAPI y a la documentación de Swagger. Si dominas estos conceptos, estarás bien preparado para diseñar y documentar API que sean potentes y fáciles de usar.
Última actualización: 21 de mayo de 2024.