Usa esquemas OpenAPI para la validación de solicitudes

Este artículo de referencia explica qué son los esquemas OpenAPI, cómo funcionan y cómo usarlos para confirmar que tus solicitudes a los endpoints de la REST API de Braze están correctamente estructuradas antes de enviarlas.

Cada página de endpoint de la REST API de Braze muestra una referencia interactiva generada a partir de una especificación OpenAPI. Cada especificación incluye un esquema: una descripción precisa y legible por máquina de los datos que un endpoint acepta y devuelve. Puedes usar ese esquema para validar tus solicitudes, de modo que detectes errores estructurales en tus propias herramientas en lugar de descubrirlos a partir de una llamada fallida a la API.

Para un resumen más amplio de cómo Braze publica estas especificaciones y los demás flujos de trabajo que admiten, consulta Uso de las especificaciones OpenAPI de Braze.

Qué es un esquema OpenAPI

Un esquema es el contrato para los datos de un endpoint. En un documento OpenAPI, el Schema Object define cada campo que utiliza un endpoint, incluido el nombre del campo, el tipo de datos, si es obligatorio, sus valores permitidos y cómo se estructuran los objetos anidados y los arrays.

Los esquemas OpenAPI se basan en JSON Schema, un estándar ampliamente adoptado para describir la estructura de los datos JSON. Dado que el contrato se expresa en un formato estándar y legible por máquina, puedes validar una carga útil con herramientas disponibles en lugar de comprobar los campos manualmente. Para obtener más información sobre los conceptos involucrados, consulta Learn OpenAPI y Understanding JSON Schema.

Cómo funcionan los esquemas

Un esquema describe datos utilizando un pequeño conjunto de bloques de construcción. Los más comunes son:

• Tipo. El tipo de datos de un valor, como string, integer, number, boolean, array u object. Consulta Data types en la documentación de Swagger.
• Campos obligatorios. Una lista de las propiedades que deben estar presentes para que los datos sean válidos.
• Restricciones. Reglas que limitan lo que un valor puede ser, como una enumeración (enum) de valores permitidos, un formato (format) (por ejemplo, date-time), un patrón de cadena, o valores mínimos y máximos.
• Estructura anidada. Los objetos pueden contener otros objetos, y los arreglos declaran el esquema de los elementos que contienen, por lo que un esquema puede describir cargas útiles con estructuras profundamente anidadas.

Un validador lee estas reglas y compara tus datos con ellas. Si falta un campo obligatorio, un valor tiene el tipo incorrecto o un valor está fuera de su conjunto permitido, el validador reporta el problema específico. La especificación de JSON Schema define este comportamiento de validación en detalle.

Cómo define un esquema una solicitud válida

Para los endpoints que aceptan un cuerpo de solicitud, el esquema del cuerpo de solicitud de la especificación describe exactamente cómo debe ser una carga útil válida. Muchos endpoints de Braze reutilizan las mismas estructuras de solicitud, como identificadores de usuario, objetos de mensajería y filtros de audiencia. Para una referencia campo por campo de esas estructuras compartidas, consulta Objetos y filtros. Considera un esquema simplificado para una solicitud que requiere una cadena external_id y un entero points, donde points no puede ser negativo:

1
2
3
4
5
6
7
8

{
  "type": "object",
  "required": ["external_id", "points"],
  "properties": {
    "external_id": { "type": "string" },
    "points": { "type": "integer", "minimum": 0 }
  }
}

Una carga útil que satisface este esquema es válida:

1

{ "external_id": "user-123", "points": 50 }

Cada una de las siguientes cargas útiles no es válida, y un validador explica por qué:

• { "points": 50 } omite el campo obligatorio external_id.
• { "external_id": "user-123", "points": "50" } envía points como una cadena en lugar de un entero.
• { "external_id": "user-123", "points": -5 } envía un valor que incumple la restricción minimum.

Al leer primero el esquema, sabes qué campos enviar, qué tipo debe tener cada valor y qué valores están permitidos, antes de realizar una sola llamada.

Validar una solicitud contra un esquema

Para validar una carga útil contra el esquema de un endpoint:

1. Descarga la especificación del endpoint que desees. Cada especificación está disponible en una URL pública y estable con el formato https://www.braze.com/docs/assets/api/openapi/{spec_filename}.yaml.
2. Extrae el esquema del cuerpo de la solicitud de la especificación.
3. Valida tu carga útil contra ese esquema con un validador de JSON Schema, como Ajv para JavaScript, u otra biblioteca de la lista de herramientas de JSON Schema para tu lenguaje.
4. Corrige cualquier campo que el validador marque como faltante, con tipo incorrecto o fuera de rango, y luego envía tu solicitud.

También puedes analizar y validar especificaciones completas con herramientas como Spectral, o generar modelos de solicitud tipados con OpenAPI Generator para que tu código produzca cargas útiles válidas por construcción. Para flujos de trabajo paso a paso que utilizan estas especificaciones, consulta Cómo usar los esquemas.

Por qué importa la validación de esquema

Validar las solicitudes contra el esquema te ayuda a:

• Detectar errores antes. Encuentra campos faltantes o mal escritos en tu propio entorno en lugar de descubrirlos por una llamada a la API rechazada.
• Reducir llamadas fallidas. Envía solicitudes bien formadas desde el primer intento, lo que disminuye los reintentos y la solución de problemas.
• Integrar con confianza. Confía en un único contrato legible por máquina en lugar de copiar las formas de las solicitudes a mano.
• Automatizar verificaciones. Agrega validación a tus pruebas o a tu pipeline de CI para que las integraciones sigan siendo correctas a medida que tu código cambia.

Recursos relacionados

• documentación de braze
• referencias externas