Ir al contenido

Esta página fue traducida automáticamente y puede contener errores. Para informar de un error de traducción, usa el componente de comentarios situado bajo el sumario, a la derecha de la página.

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 consistente y estructurado. Cada especificación es también un archivo legible por máquina que puedes descargar y utilizar directamente en tus propias herramientas.

Nota

La referencia en cada página de endpoint es de solo lectura. No envía solicitudes en vivo desde el sitio de documentación. Para llamar a un endpoint, 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 REST API, busca la sección Endpoint reference. Para abrir la especificación sin procesar, usa la opción de descarga de especificaciones en esa sección. 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 documento OpenAPI 3 único e 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é los esquemas son valiosos

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. Dado que este contrato es legible por máquina, puedes confiar en él en lugar de copiar manualmente las formas de solicitudes y respuestas. Para los objetos y filtros reutilizables que comparten muchos endpoints, consulta Objetos y filtros. Los esquemas te ayudan a:

Generar código de cliente y SDKs. Producir modelos de solicitud y respuesta tipados, o una biblioteca de cliente completa, en tu lenguaje preferido para que no tengas que escribir cuerpos de solicitud a mano.
Validar solicitudes y respuestas. Verificar las cargas útiles contra el esquema antes de enviarlas y confirmar que las respuestas coinciden con lo que esperas, lo que detecta errores de integración de forma temprana.
Simular la API. Levantar un servidor simulado a partir de la especificación para que puedas construir y probar contra los endpoints de Braze antes de escribir código de integración en vivo.
Importar en clientes de API. Cargar la especificación en herramientas como Postman o Insomnia para obtener solicitudes prellenadas, descripciones de parámetros y autocompletado.
Mantener las integraciones sincronizadas. Comparar una copia almacenada de una especificación con la versión actual para detectar cuándo se agrega o cambia un campo, y luego actualizar tu integración con confianza.

Cómo usar los esquemas

Las siguientes instrucciones asumen que ya descargaste un archivo de especificaciones desde una página de endpoint.

Ver y explorar una especificación

Para leer una especificación en una vista estructurada e interactiva, usa cualquier visor de OpenAPI:

Descarga el archivo de especificaciones del endpoint que deseas.
Abre Swagger Editor o un visor similar.
Pega o sube el archivo para explorar la operación, sus parámetros y cada esquema que define.

Generar un cliente o modelos

Para convertir un esquema en código tipado en tu lenguaje, usa un generador de OpenAPI:

Instala un generador como OpenAPI Generator.
Apunta el generador al archivo de especificaciones y selecciona tu lenguaje de destino.
Usa los modelos de solicitud y respuesta generados, o el cliente completo, en tu aplicación en lugar de construir cuerpos de solicitud manualmente.

Validar tus cargas útiles

Para confirmar que el cuerpo de una solicitud coincide con el contrato del endpoint antes de enviarlo:

Extrae el esquema del cuerpo de la solicitud de la especificación.
Usa un validador de JSON Schema, o una biblioteca en tu lenguaje, para validar tu carga útil contra ese esquema.
Corrige cualquier campo que el validador marque como faltante, con tipo incorrecto o fuera de rango.

Importar en Postman u otro cliente

Para obtener solicitudes prellenadas y descripciones de campos en línea:

En Postman, selecciona Import y luego elige el archivo de especificaciones descargado.
Postman crea una colección con el endpoint, sus parámetros y valores de ejemplo.
Agrega tu clave de API REST y el endpoint REST de destino, y luego envía tu solicitud.

Simular el endpoint

Para desarrollar contra un endpoint antes de escribir 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 luego cambia a tu endpoint REST en vivo cuando estés listo.

New Stuff!