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.
Vous pouvez envoyer une requête depuis la référence avec Test Request. Saisissez une clé API REST dans le champ Bearer Token et sélectionnez votre endpoint REST dans la liste des serveurs. La requête s’exécute sur votre espace de travail et modifie des données réelles : utilisez donc une clé associée à un espace de travail de test. Les endpoints qui utilisent PUT, PATCH ou DELETE ne peuvent pas être appelés depuis le site de documentation, c’est pourquoi ils n’affichent pas Test Request. Pour ces endpoints, 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, sélectionnez Télécharger le document OpenAPI dans la référence, ou utilisez le lien de téléchargement en bas de la page. Chaque fichier est disponible à une URL publique et stable au format suivant :
https://www.braze.com/docs/assets/api/openapi/{spec_filename}.yaml
Chaque fichier est un document OpenAPI 3 unique et autonome, consacré à un seul endpoint. Le document comprend les schémas de requête et de réponse, qui décrivent précisément la structure des données que l’endpoint accepte et renvoie.
Pourquoi les schémas sont utiles
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. Comme ce contrat est lisible par une machine, vous pouvez vous appuyer dessus au lieu de recopier à la main la structure des requêtes et des réponses. Pour les objets et filtres réutilisables communs à 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 typés de requêtes et de réponses, ou une bibliothèque client complète, dans le langage de votre choix pour ne pas avoir à écrire les corps de requête à la main.
- Valider les requêtes et les réponses. Vérifiez vos 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 tôt les bugs d’intégration.
- Simuler l’API. Déployez un serveur fictif à partir de la spécification pour créer et tester votre intégration avec les endpoints de 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.
- Garder vos intégrations synchronisées. Comparez une copie enregistrée d’une spécification avec la version actuelle pour repérer 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 partent du principe que vous avez téléchargé un fichier de spécification depuis la page d’un endpoint.
Consulter 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 qui vous intéresse.
- Ouvrez Swagger Editor ou un visualiseur similaire.
- Collez ou importez le fichier pour parcourir l’opération, ses paramètres et tous les schémas 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.
- Indiquez au générateur 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 créer manuellement les corps de requête.
Valider vos payloads
Pour vérifier qu’un corps de requête respecte le contrat de l’endpoint avant de l’envoyer :
- Extrayez le schéma du corps de requête de la spécification.
- Utilisez un validateur JSON Schema, ou une bibliothèque de votre langage, pour valider votre payload par rapport à ce schéma.
- Corrigez 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 contenant l’endpoint, ses paramètres et des exemples de valeurs.
- Ajoutez votre clé d’API REST et l’endpoint REST cible, puis envoyez votre requête.
Simuler l’endpoint
Pour développer avec un endpoint avant d’écrire le 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.
- Faites pointer votre application vers le serveur de simulation pendant le développement, puis basculez vers votre endpoint REST en production lorsque vous êtes prêt.