¿Cómo define OpenAPI las respuestas?

¿Cómo define OpenAPI las respuestas? #

OpenAPI se ha convertido en uno de los pilares centrales del desarrollo moderno de API, ya que ofrece una forma estandarizada de describir, producir y consumir servicios web RESTful. Uno de sus componentes principales es la manera en que define las respuestas de los endpoints de una API. Este artículo analiza en detalle cómo define OpenAPI las respuestas y explora el esquema, la estructura y los distintos matices de las definiciones de respuesta.

Comprender OpenAPI #

Antes de entrar en los detalles de las definiciones de respuesta, conviene tener una idea básica de qué es OpenAPI. OpenAPI, antes conocido como Swagger, es una especificación para crear, documentar y consumir API REST. La especificación OpenAPI (OAS) permite a los desarrolladores definir la estructura y el comportamiento de las API REST de forma independiente del lenguaje. Una parte fundamental de esta especificación es el objeto de respuesta, que detalla el resultado esperado de un endpoint de una API.

El papel de las respuestas en OpenAPI #

En un documento OpenAPI, las respuestas son una parte fundamental de las definiciones de los endpoints de la API. Cada endpoint de la API tendrá varias respuestas, que indican los posibles resultados cuando se invoca el endpoint. Las respuestas incluyen no solo el contenido de la respuesta, sino también los códigos de estado y los posibles mensajes de error que puede recibir el cliente.

Estructura básica de un objeto de respuesta #

Un objeto de respuesta en OpenAPI se define dentro de la sección responses de la definición de un endpoint. Este es un ejemplo básico:

paths:
  /users:
    get:
      summary: Retrieve a list of users
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '400':
          description: Bad request
        '500':
          description: Internal server error

En este fragmento de YAML:

Cada respuesta se identifica por su código de estado HTTP (por ejemplo, 200, 400, 500).
Cada respuesta incluye un campo description, que proporciona una descripción legible por personas de la respuesta.
El campo content especifica el tipo de medio y el esquema de la respuesta.

Componentes detallados de una respuesta #

Códigos de estado #

Los códigos de estado son fundamentales para que los clientes interpreten los resultados de sus solicitudes. OpenAPI permite definir respuestas para cualquier código de estado HTTP estándar, como 200 para una solicitud correcta, 400 para una solicitud incorrecta, 404 para recurso no encontrado y 500 para error interno del servidor. También puedes definir códigos de estado personalizados que se adapten a las necesidades de tu aplicación.

Descripciones #

Cada respuesta debe tener un campo description. Se trata de una explicación legible por personas de la respuesta y puede contener detalles útiles tanto para desarrolladores como para usuarios finales. Es una buena práctica proporcionar descripciones claras y concisas para evitar ambigüedades.

Contenido #

El campo content se utiliza para definir el tipo de medio y el esquema del cuerpo de la respuesta. Esto ayuda a los desarrolladores a comprender la estructura de los datos que devolverá la API. Una configuración típica consiste en especificar el tipo de medio, como application/json, y a continuación detallar el esquema de la respuesta.

Este es un ejemplo de una definición de respuesta más detallada:

responses:
  '200':
    description: A list of users
    content:
      application/json:
        schema:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
                format: int64
              username:
                type: string
              email:
                type: string

Encabezados #

En ocasiones, las API necesitan devolver datos en los encabezados y no solo en el cuerpo. OpenAPI permite definir encabezados dentro de los objetos de respuesta:

responses:
  '200':
    description: Successful operation
    headers:
      X-Rate-Limit-Limit:
        description: The number of allowed requests in the current period
        schema:
          type: integer
      X-Rate-Limit-Remaining:
        description: The number of remaining requests in the current period
        schema:
          type: integer

Links #

OpenAPI 3.0 introdujo el concepto de links, similares a los hipervínculos de HTML. Permiten proporcionar información sobre cómo se pueden realizar también operaciones relacionadas:

responses:
  '201':
    description: Created user
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/User'
    links:
      GetUserById:
        operationId: getUserById
        parameters:
          id: '$response.body#/id'

Componentes y reutilización #

Una de las ventajas de OpenAPI es la posibilidad de reutilizar componentes en distintas partes de la definición de la API. Esto incluye los objetos de respuesta. Al definir las respuestas comunes en la sección components de tu documento OpenAPI, puedes referenciarlas fácilmente en otros lugares, lo que fomenta el principio DRY (Don’t Repeat Yourself, no te repitas).

Este es un ejemplo de cómo definir una respuesta común en la sección components y luego referenciarla:

components:
  responses:
    NotFound:
      description: Entity not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
paths:
  /users/{id}:
    get:
      summary: Retrieve a user by ID
      responses:
        '200':
          description: A user object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          $ref: '#/components/responses/NotFound'

Definición de esquemas para las respuestas #

Para proporcionar una estructura clara a los datos que devuelve un endpoint de una API, OpenAPI utiliza esquemas. Estos pueden ser tipos simples como string o integer, o tipos complejos definidos mediante la notación de JSON Schema.

Este es un ejemplo de una definición de esquema más compleja en la sección components:

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        username:
          type: string
        email:
          type: string
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string

Incorporar estos esquemas a tus respuestas garantiza que quien consume la API sepa exactamente qué esperar, lo que reduce los errores y mejora la experiencia del desarrollador.

Negociación de contenido en las respuestas #

Muchas API modernas ofrecen datos en varios formatos, como JSON, XML o incluso texto sin formato. OpenAPI admite la negociación de contenido al permitir varios tipos de medio para una misma respuesta:

responses:
  '200':
    description: A list of users
    content:
      application/json:
        schema:
          type: array
          items:
            $ref: '#/components/schemas/User'
      application/xml:
        schema:
          type: array
          items:
            $ref: '#/components/schemas/User'

Esta característica permite que las API sean más flexibles y se adapten a los distintos requisitos de los clientes.

Ejemplo de un documento OpenAPI completo #

A continuación se muestra un ejemplo conciso de un documento OpenAPI completo que define un endpoint /users con definiciones de respuesta detalladas:

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Retrieve a list of users
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
  /users/{id}:
    get:
      summary: Retrieve a user by ID
      parameters:
        - name: id
          in: path
          required: true
          description: The user ID
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: A user object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        username:
          type: string
        email:
          type: string
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Entity not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

Conclusión #

OpenAPI ofrece una forma estructurada y detallada de definir las respuestas de los endpoints de tu API, lo que facilita que desarrolladores y consumidores comprendan e interactúen con ella. Al aprovechar los códigos de estado HTTP, las descripciones detalladas, los esquemas de contenido, los encabezados y los links, puedes proporcionar una documentación completa y mejorar la experiencia general del desarrollador.

Para obtener más información y recursos, puedes visitar la OpenAPI Initiative y explorar con más detalle la especificación OpenAPI.

Última actualización: 21 de mayo de 2024.