Utiliser les spécifications OpenAPI de Braze
Cet article de référence explique comment Braze publie des spécifications OpenAPI pour ses endpoints REST API et comment vous pouvez utiliser les schémas de ces spécifications pour accélérer vos workflows de développement.
Chaque page d’endpoint REST API de Braze affiche une référence interactive générée à partir d’une spécification OpenAPI. La référence présente les paramètres de l’endpoint, le corps de la requête, les schémas de réponse et des exemples de réponse dans un format structuré et cohérent. Chaque spécification est également un fichier lisible par une machine que vous pouvez télécharger et utiliser directement dans vos propres outils.
La référence sur chaque page d’endpoint est en lecture seule. Elle n’envoie pas de requêtes en direct depuis le site de documentation. Pour appeler un endpoint, copiez l’exemple cURL généré ou utilisez la spécification téléchargée dans votre propre client, comme décrit dans Comment utiliser les schémas.
Où trouver une spécification
Sur n’importe quelle page d’endpoint de la REST API, recherchez la section Endpoint reference. Pour ouvrir la spécification brute, utilisez l’option de téléchargement de spécification dans cette section. Chaque fichier est accessible à une URL publique stable au format suivant :
https://www.braze.com/docs/assets/api/openapi/{spec_filename}.yaml
Chaque fichier est un document OpenAPI 3 autonome pour un seul endpoint. Le document inclut les schémas de requête et de réponse qui décrivent la structure exacte des données acceptées et renvoyées par l’endpoint.
Pourquoi les schémas sont précieux
Un schéma est le contrat structuré d’un endpoint : il définit le nom de chaque champ, son type de données, son caractère obligatoire ou non, ses valeurs autorisées et la manière dont les objets s’imbriquent. Ce contrat étant lisible par une machine, vous pouvez vous y fier au lieu de copier manuellement les structures de requêtes et de réponses. Pour les objets et filtres réutilisables partagés par de nombreux endpoints, consultez Objets et filtres. Les schémas vous aident à :
- Générer du code client et des SDK. Produisez des modèles de requêtes et de réponses typés, ou une bibliothèque client complète, dans le langage de votre choix afin de ne pas rédiger manuellement les corps de requêtes.
- Valider les requêtes et les réponses. Vérifiez les payloads par rapport au schéma avant de les envoyer et confirmez que les réponses correspondent à vos attentes, ce qui permet de détecter les bugs d’intégration en amont.
- Simuler l’API. Déployez un serveur fictif à partir de la spécification afin de développer et tester vos appels vers les endpoints Braze avant d’écrire le code d’intégration en production.
- Importer dans des clients API. Chargez la spécification dans des outils comme Postman ou Insomnia pour obtenir des requêtes préremplies, des descriptions de paramètres et l’autocomplétion.
- Maintenir vos intégrations à jour. Comparez une copie enregistrée d’une spécification avec la version actuelle pour détecter l’ajout ou la modification d’un champ, puis mettez à jour votre intégration en toute confiance.
Comment utiliser les schémas
Les instructions suivantes supposent que vous avez téléchargé un fichier de spécification depuis une page d’endpoint.
Afficher et explorer une spécification
Pour lire une spécification dans une vue structurée et interactive, utilisez n’importe quel visualiseur OpenAPI :
- Téléchargez le fichier de spécification de l’endpoint souhaité.
- Ouvrez Swagger Editor ou un visualiseur similaire.
- Collez ou importez le fichier pour parcourir l’opération, ses paramètres et chaque schéma qu’il définit.
Générer un client ou des modèles
Pour transformer un schéma en code typé dans votre langage, utilisez un générateur OpenAPI :
- Installez un générateur tel que OpenAPI Generator.
- Pointez le générateur vers le fichier de spécification et sélectionnez votre langage cible.
- Utilisez les modèles de requête et de réponse générés, ou le client complet, dans votre application au lieu de construire manuellement les corps de requête.
Valider vos payloads
Pour confirmer qu’un corps de requête correspond au contrat de l’endpoint avant de l’envoyer :
- Extrayez le schéma du corps de requête à partir de la spécification.
- Utilisez un validateur JSON Schema, ou une bibliothèque dans votre langage, pour valider votre payload par rapport à ce schéma.
- Corrigez tous les champs que le validateur signale comme manquants, mal typés ou hors limites.
Importer dans Postman ou un autre client
Pour obtenir des requêtes préremplies et des descriptions de champs intégrées :
- Dans Postman, sélectionnez Import, puis choisissez le fichier de spécification téléchargé.
- Postman crée une collection avec l’endpoint, ses paramètres et des valeurs d’exemple.
- Ajoutez votre clé REST API et votre endpoint REST cible, puis envoyez votre requête.
Simuler l’endpoint
Pour développer autour d’un endpoint avant d’écrire du code d’intégration en production :
- Chargez la spécification dans un outil de simulation, tel que Prism.
- Démarrez le serveur de simulation, qui renvoie des réponses conformes aux schémas de la spécification.
- Pointez votre application vers le serveur de simulation pendant le développement, puis basculez vers votre endpoint REST en production lorsque vous êtes prêt.