Uso de las especificaciones OpenAPI de Braze
Este artículo de referencia explica cómo Braze publica especificaciones OpenAPI para sus endpoints de REST API y cómo puedes utilizar los esquemas de esas especificaciones para acelerar tus flujos de trabajo de desarrollo.
Cada página de endpoint de la REST API de Braze muestra una referencia interactiva generada a partir de una especificación OpenAPI. La referencia muestra los parámetros del endpoint, el cuerpo de la solicitud, los esquemas de respuesta y las respuestas de ejemplo en un formato coherente y estructurado. Cada especificación es también un archivo legible por máquina que puedes descargar y utilizar directamente en tus propias herramientas.
Puedes enviar una solicitud desde la referencia con Test Request. Introduce una clave de API REST en el campo Bearer Token y selecciona tu endpoint REST en la lista de servidores. La solicitud se ejecuta en tu espacio de trabajo y modifica datos reales, así que utiliza una clave de un espacio de trabajo de prueba. Los endpoints que utilizan PUT, PATCH o DELETE no se pueden enviar desde el sitio de documentación, por lo que no muestran Test Request. Para esos endpoints, copia el ejemplo cURL generado o utiliza la especificación descargada en tu propio cliente, como se describe en Cómo utilizar los esquemas.
Dónde encontrar una especificación
En cualquier página de endpoint de la REST API, selecciona Download OpenAPI Document en la referencia o usa el enlace de descarga al final de la página. Cada archivo se encuentra en una URL pública y estable con el siguiente formato:
https://www.braze.com/docs/assets/api/openapi/{spec_filename}.yaml
Cada archivo es un único documento OpenAPI 3 independiente para un endpoint. El documento incluye los esquemas de solicitud y respuesta que describen la forma exacta de los datos que el endpoint acepta y devuelve.
Por qué son útiles los esquemas
Un esquema es el contrato estructurado de un endpoint: define el nombre de cada campo, su tipo de datos, si el campo es obligatorio, sus valores permitidos y cómo se anidan los objetos. Como este contrato es legible por máquina, puedes confiar en él en lugar de copiar a mano la estructura de las solicitudes y respuestas. Para ver los objetos y filtros reutilizables que comparten muchos endpoints, consulta Objetos y filtros. Los esquemas te ayudan a:
- Generar código de cliente y SDK. Crea modelos tipados de solicitud y respuesta, o una biblioteca de cliente completa, en tu lenguaje preferido para no tener que escribir a mano los cuerpos de las solicitudes.
- Validar solicitudes y respuestas. Comprueba las cargas útiles con el esquema antes de enviarlas y confirma que las respuestas coinciden con lo que esperas, lo que permite detectar pronto los errores de integración.
- Simular la API. Levanta un servidor simulado a partir de la especificación para que puedas crear y probar con los endpoints de Braze antes de escribir código de integración en vivo.
- Importar en clientes de API. Carga la especificación en herramientas como Postman o Insomnia para obtener solicitudes precompletadas, descripciones de parámetros y autocompletado.
- Mantener las integraciones sincronizadas. Compara una copia guardada de una especificación con la versión actual para detectar cuándo se añade o cambia un campo y, después, actualiza tu integración con confianza.
Cómo utilizar los esquemas
Las siguientes instrucciones dan por hecho que ya descargaste un archivo de especificación desde la página de un endpoint.
Ver y explorar una especificación
Para leer una especificación en una vista estructurada e interactiva, utiliza cualquier visor de OpenAPI:
- Descarga el archivo de especificación del endpoint que quieras.
- Abre Swagger Editor o un visor similar.
- Pega o carga el archivo para explorar la operación, sus parámetros y todos los esquemas que define.
Generar un cliente o modelos
Para convertir un esquema en código tipado en tu lenguaje, utiliza un generador de OpenAPI:
- Instala un generador como OpenAPI Generator.
- Apunta el generador al archivo de especificación y selecciona tu lenguaje de destino.
- Utiliza en tu aplicación los modelos de solicitud y respuesta generados, o el cliente completo, en lugar de crear manualmente los cuerpos de las solicitudes.
Validar tus cargas útiles
Para confirmar que el cuerpo de una solicitud cumple el contrato del endpoint antes de enviarla:
- Extrae de la especificación el esquema del cuerpo de la solicitud.
- Utiliza un validador de JSON Schema, o una biblioteca de tu lenguaje, para validar tu carga útil con ese esquema.
- Corrige los campos que el validador marque como ausentes, con un tipo incorrecto o fuera de rango.
Importar en Postman u otro cliente
Para obtener solicitudes prellenadas y descripciones de los campos en línea:
- En Postman, selecciona Importar y, a continuación, elige el archivo de especificación descargado.
- Postman crea una colección con el endpoint, sus parámetros y valores de ejemplo.
- Añade tu clave de API REST y el endpoint REST de destino y, después, envía tu solicitud.
Simular el endpoint
Para desarrollar con un endpoint antes de escribir el código de integración en vivo:
- Carga la especificación en una herramienta de simulación, como Prism.
- Inicia el servidor simulado, que devuelve respuestas que coinciden con los esquemas de la especificación.
- Apunta tu aplicación al servidor simulado mientras desarrollas y, cuando estés listo, cambia a tu endpoint REST en vivo.