¿Cómo admite OpenAPI la validación de datos?

¿Cómo admite OpenAPI la validación de datos? #

OpenAPI, antes conocido como Swagger, es una especificación ampliamente utilizada para describir y documentar API RESTful. Ofrece un método coherente y legible por máquinas para definir los elementos de una API, lo que hace que el desarrollo de API sea más sencillo, estable y eficaz. Uno de los aspectos críticos al trabajar con API es garantizar que tanto las solicitudes como las respuestas se ajusten a los formatos y las restricciones especificados, lo que se conoce comúnmente como validación de datos.

¿Qué es la validación de datos? #

La validación de datos es el proceso de asegurarse de que los datos cumplan ciertos criterios antes de procesarse o almacenarse. En el contexto de las API, la validación puede ocurrir en varias etapas, entre ellas:

  • Validar los parámetros de la solicitud.
  • Validar el cuerpo de la solicitud frente a un esquema.
  • Validar los datos de la respuesta antes de devolverlos al cliente.

OpenAPI ofrece un sólido soporte para la validación de datos mediante sus definiciones de esquema, que utilizan JSON Schema, un potente lenguaje de esquemas para documentos JSON. Esto garantiza flexibilidad y solidez al definir la estructura y las restricciones de los datos de la API.

Descripción general de OpenAPI #

Antes de profundizar en cómo OpenAPI admite específicamente la validación de datos, es importante entender su estructura básica. Un documento OpenAPI es, en esencia, un archivo JSON o YAML que describe:

  • Los endpoints disponibles (/users, /orders).
  • Las operaciones de cada endpoint (GET, POST).
  • Los parámetros de entrada de cada endpoint y operación.
  • Las respuestas de cada operación.
  • Los modelos o esquemas que definen la estructura de los datos utilizados en las solicitudes y respuestas.

Para obtener más información sobre OpenAPI, puedes visitar el sitio web oficial de OpenAPI.

Definiciones de esquemas #

En OpenAPI, los esquemas definen la estructura de los datos de las solicitudes y respuestas. Puedes especificar los esquemas en una sección components y referenciarlos a lo largo de la descripción de tu API. Los esquemas se basan en JSON Schema, lo que permite un control detallado sobre los tipos de datos y las reglas de validación.

Este es un ejemplo de definición de un esquema:

openapi: 3.0.1
info:
  title: Simple API
  version: '1.0'
paths:
  /users:
    get:
      summary: Get list of users
      responses:
        '200':
          description: Successfully retrieved users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
          minLength: 1
          maxLength: 100
        email:
          type: string
          format: email
      required:
        - id
        - name
        - email

En este ejemplo:

  • El esquema User se define en components.schemas.
  • El esquema User especifica que un objeto de usuario debe tener los campos id, name y email.
  • Se añaden reglas específicas a cada campo para su validación, como minLength, maxLength y format.

Tipos de datos y formatos #

OpenAPI admite una variedad de tipos de datos y formatos, lo que permite una validación exhaustiva:

  • Tipos primitivos: string, number, integer, boolean, array, object.
  • Formatos de cadena: email, uuid, uri, hostname, date-time, etc.

Ejemplo #

openapi: 3.0.1
info:
  title: Example API
  version: '1.0'
paths:
  /orders:
    post:
      summary: Create a new order
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
      responses:
        '201':
          description: Successfully created order
components:
  schemas:
    Order:
      type: object
      properties:
        orderId:
          type: string
          format: uuid
        products:
          type: array
          items:
            type: string
        orderDate:
          type: string
          format: date-time
      required:
        - orderId
        - products
        - orderDate

El esquema Order valida que:

  • orderId debe ser una cadena con formato UUID.
  • products debe ser un arreglo (array) de cadenas.
  • orderDate debe ser una cadena con formato date-time.

Definición de restricciones #

OpenAPI permite aplicar restricciones adicionales a los datos para asegurar que cumplan criterios específicos. Entre las restricciones más comunes se encuentran:

  • Restricciones de longitud: minLength y maxLength para cadenas; minItems y maxItems para arreglos.
  • Restricciones numéricas: minimum, maximum, exclusiveMinimum, exclusiveMaximum.
  • Patrón (pattern): expresiones regulares para patrones de cadenas.

Ejemplo #

components:
  schemas:
    Product:
      type: object
      properties:
        id:
          type: integer
          minimum: 1
        name:
          type: string
          pattern: '^[A-Za-z ]+$'
        price:
          type: number
          minimum: 0.01

En este ejemplo, el esquema Product especifica que:

  • id debe ser un entero mayor o igual que 1.
  • name debe ser una cadena que coincida con el patrón de solo caracteres alfabéticos y espacios.
  • price debe ser un número mayor o igual que 0.01.

Uso de bibliotecas de validación #

Varias bibliotecas y herramientas pueden utilizar los esquemas de OpenAPI para validar automáticamente los datos de las solicitudes y respuestas. Algunas de las más populares son:

Ejemplo con express-openapi-validator #

Este es un ejemplo de implementación para validar solicitudes con express-openapi-validator en una aplicación Node.js:

const express = require('express');
const { OpenApiValidator } = require('express-openapi-validator');
const app = express();

app.use(express.json());

// Load the OpenAPI document (YAML or JSON)
const apiSpec = require('./api-spec.yaml');

new OpenApiValidator({ apiSpec }).install(app)
  .then(() => {
    app.post('/orders', (req, res) => {
      res.status(201).send({ message: 'Order Created successfully' });
    });

    app.use((err, req, res, next) => {
      // handle validation errors
      res.status(err.status || 500).json({ 
        message: err.message, 
        errors: err.errors 
      });
    });

    app.listen(3000, () => {
      console.log('Server is running on port 3000');
    });
  });

Este ejemplo muestra cómo usar express-openapi-validator para aplicar la validación de solicitudes basada en una especificación OpenAPI. Los errores se capturan y se devuelven al cliente con los códigos de estado y los mensajes adecuados.

Aplicaciones en el mundo real #

La validación es fundamental para garantizar la exactitud y la integridad de los datos en aplicaciones reales. Estos son algunos ejemplos:

  • Servicios de pago: garantizar que los detalles de las transacciones, como los números de tarjeta y las fechas de vencimiento, sean válidos.
  • Registro de usuarios: asegurar que los nombres de usuario, las direcciones de correo electrónico y las contraseñas cumplan los criterios especificados de seguridad y usabilidad.
  • Plataformas de comercio electrónico: validar los detalles de los productos, los precios y la información de los pedidos para mantener la coherencia de los datos.

Empresas como Stripe, PayPal y Shopify utilizan rigurosas comprobaciones de validación para garantizar servicios sólidos y confiables.

Conclusión #

OpenAPI ofrece amplias herramientas para definir y validar estructuras de datos en las API. Gracias a su uso de JSON Schema, permite a quienes desarrollan API aplicar restricciones de datos y mantener su integridad sin esfuerzo. Al aprovechar estas capacidades, los desarrolladores pueden crear API más confiables y coherentes, mejorando la experiencia general del usuario y la robustez del sistema.

Para profundizar en el tema, puedes consultar:

Con OpenAPI, puedes asegurarte de que los datos de tu API sean siempre válidos, lo que se traduce en menos errores, una depuración más sencilla y un entorno más estable para los consumidores de la API.

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

Este sitio web no está afiliado a la OpenAPI Initiative.