Utiliser les schémas OpenAPI pour la validation des requêtes
Cet article de référence explique ce que sont les schémas OpenAPI, comment ils fonctionnent, et comment les utiliser pour vérifier que vos requêtes aux endpoints de la REST API Braze sont correctement structurées avant de les envoyer.
Chaque page d’endpoint de la REST API Braze affiche une référence interactive générée à partir d’une spécification OpenAPI. Chaque spécification inclut un schéma : une description précise et lisible par une machine des données qu’un endpoint accepte et retourne. Vous pouvez utiliser ce schéma pour valider vos requêtes, de sorte que vous détectiez les erreurs structurelles dans vos propres outils au lieu de les découvrir à la suite d’un appel API échoué.
Pour un aperçu plus général de la façon dont Braze publie ces spécifications et des autres workflows qu’elles prennent en charge, consultez Utiliser les spécifications OpenAPI de Braze.
Qu’est-ce qu’un schéma OpenAPI
Un schéma est le contrat qui définit les données d’un endpoint. Dans un document OpenAPI, le Schema Object décrit chaque champ utilisé par un endpoint, y compris son nom, son type de données, s’il est obligatoire, ses valeurs autorisées, et la manière dont les objets imbriqués et les tableaux sont structurés.
Les schémas OpenAPI reposent sur JSON Schema, un standard largement adopté pour décrire la structure des données JSON. Le contrat étant exprimé dans un format standard et lisible par les machines, vous pouvez valider un payload à l’aide d’outils prêts à l’emploi plutôt que de vérifier les champs manuellement. Pour en savoir plus sur les concepts impliqués, consultez Learn OpenAPI et Understanding JSON Schema.
Fonctionnement des schémas
Un schéma décrit les données à l’aide d’un petit ensemble de briques de base. Les plus courants sont :
- Type. Le type de données d’une valeur, tel que
string,integer,number,boolean,arrayouobject. Consultez Data types dans la documentation Swagger. - Champs obligatoires. Une liste des propriétés qui doivent être présentes pour que les données soient valides.
- Contraintes. Des règles qui restreignent les valeurs possibles, telles qu’un
enumde valeurs autorisées, unformat(par exemple,date-time), un modèle de chaîne de caractères, ou des valeurs minimales et maximales. - Structure imbriquée. Les objets peuvent contenir d’autres objets, et les tableaux déclarent le schéma des éléments qu’ils contiennent, ce qui permet à un schéma de décrire des payloads profondément structurés.
Un validateur lit ces règles et compare vos données par rapport à celles-ci. Si un champ obligatoire est manquant, si une valeur a un type incorrect, ou si une valeur se situe en dehors de l’ensemble autorisé, le validateur signale le problème spécifique. La spécification JSON Schema définit ce comportement de validation en détail.
Comment un schéma définit une requête valide
Pour les endpoints qui acceptent un corps de requête, le schéma du corps de requête défini dans la spécification décrit exactement à quoi ressemble un payload valide. De nombreux endpoints Braze réutilisent les mêmes structures de requête, telles que les identifiants utilisateur, les objets de messaging et les filtres d’audience. Pour une référence champ par champ de ces structures partagées, consultez Objets et filtres. Prenons l’exemple d’un schéma simplifié pour une requête qui nécessite un external_id de type string et un points de type integer, où points ne peut pas être négatif :
{
"type": "object",
"required": ["external_id", "points"],
"properties": {
"external_id": { "type": "string" },
"points": { "type": "integer", "minimum": 0 }
}
}
Un payload qui satisfait ce schéma est valide :
{ "external_id": "user-123", "points": 50 }
Chacun des payloads suivants est invalide, et un validateur explique pourquoi :
{ "points": 50 }omet le champ obligatoireexternal_id.{ "external_id": "user-123", "points": "50" }envoiepointssous forme de string au lieu d’un integer.{ "external_id": "user-123", "points": -5 }envoie une valeur qui enfreint la contrainteminimum.
En lisant le schéma en premier, vous savez quels champs envoyer, quel type chaque valeur doit avoir et quelles valeurs sont autorisées, avant même d’effectuer un seul appel.
Valider une requête par rapport à un schéma
Pour valider un payload par rapport au schéma d’un endpoint :
- Téléchargez la spécification de l’endpoint souhaité. Chaque spécification est disponible à une URL publique stable au format
https://www.braze.com/docs/assets/api/openapi/{spec_filename}.yaml. - Extrayez le schéma du corps de la requête à partir de la spécification.
- Validez votre payload par rapport à ce schéma à l’aide d’un validateur JSON Schema, tel qu’Ajv pour JavaScript, ou une autre bibliothèque de la liste JSON Schema tools pour votre langage.
- Corrigez les champs que le validateur signale comme manquants, mal typés ou hors limites, puis envoyez votre requête.
Vous pouvez également analyser et valider des spécifications entières avec des outils tels que Spectral, ou générer des modèles de requête typés avec OpenAPI Generator afin que votre code produise des payloads valides dès la conception. Pour des workflows étape par étape utilisant ces spécifications, consultez Comment utiliser les schémas.
Pourquoi la validation de schéma est importante
Valider les requêtes par rapport au schéma vous permet de :
- Détecter les erreurs plus tôt. Repérez les champs manquants ou mal saisis dans votre propre environnement plutôt qu’à la suite d’un appel API rejeté.
- Réduire les appels échoués. Envoyez des requêtes correctement formatées dès la première fois, ce qui diminue les nouvelles tentatives et la résolution des problèmes.
- Intégrer en toute confiance. Appuyez-vous sur un contrat unique et lisible par les machines plutôt que de reproduire manuellement la structure des requêtes.
- Automatiser les vérifications. Ajoutez la validation à vos tests ou à votre pipeline CI pour que vos intégrations restent conformes à mesure que votre code évolue.