Dans cette article :
Si vous obtenez l'erreur suivante en réponse à une requête envoyée à notre API :
“The request you submitted did not match the schema the API was expecting. Please be sure that you submitted your request with the correct Content-Type header and that your request body matches our schema. See the API documentation for the JSON schema to follow.”
Cela signifie que vous avez une erreur avec la structure de données JSON que vous avez incluse dans le corps de votre requête et que celle-ci ne respecte pas le format dans lequel nous nous attendions à la recevoir. Afin de connaître précisément ce qui cloche avec vos données JSON, vous devrez les valider en ayant recours à un schéma JSON.
Qu'est-ce qu'un schéma JSON ?
Un schéma JSON c'est :
“JSON Schema specifies a JSON-based format to define the structure of JSON data for validation, documentation, and interaction control. It provides a contract for the JSON data required by a given application, and how that data can be modified.” Wikipedia
En français, ceci pourrait se traduire par :
Un schéma JSON, lui même décrit en JSON, spécifie comment structurer des données selon le format JSON à des fins de validation, documentation et de contrôle des interactions. Il consiste en un contrat que la structure de donnée JSON doit respecter afin de pouvoir être soumise à un système.
Comment identifier où se trouve l'erreur dans mon schéma JSON ?
Pour trouver ce qui est incorrect dans votre structure de données JSON, vous devrez utiliser un valideur de Schéma JSON.
L'utilisation d'un valideur de Schéma JSON consiste à comparer deux éléments entre eux. Ces éléments sont : notre schéma JSON et votre structure de données JSON. Le valideur indiquera ensuite les endroits où votre structure de données ne correspond pas à ce qui est attendu par notre API.
Résoudre les erreurs de structures de données JSON en trois étapes :
Étape 1 : Obtenir votre structure de données JSON
Normalement, vous devriez déjà l’avoir puisque vous avez tenté de faire une requête à notre API... qui a malheureusement échoué avec une erreur de validation de schéma JSON.
Voici un exemple de structure de données JSON qui contient une erreur et qui nous servira d'exemple dans les prochaines étapes :
{
"batchType": "addMembers",
"relationType": 28,
"defaultConsentDate": "2014-06-15",
"defaultConsentProof": "Bought on our website",
"members": [
{
"firstname": "John",
"lastname": "Doe",
"company": "John Doe Company",
"email": "john.doe@example.org",
"gender": "m",
"language": "fr_ca",
"postalCode": "A0A 0A0",
"country": "CA",
"note": "John is the CEO",
"birthdate": "1980-01-01",
"customField1": "This is a test !"
}
]
}
Étape 2 : Obtenir notre schéma JSON
Notre API vous permet actuellement de nous soumettre deux types de requêtes en lot (batches). Un schéma JSON est fourni pour chacune d'elle. Dans le cas de l'exemple précédent, il s’agit d’une requête en lot de type “addMembers”. Voici donc comment procéder pour obtenir le bon schéma à partir de la documentation de notre API :
- Accédez à la documentation de notre API ici : https://cyberimpactapiv4.docs.apiary.io
- Dans la section de gauche, cliquez sur “Resources” (ressources).
- Dans la liste de “Resources” (ressources) qui apparaît, cliquez sur “Batches”.
- Faites défiler la partie centrale jusqu’à la section “Add a batch” et cliquez sur celle-ci.
- Faites défiler la partie de droite jusqu’à la section “Request – Add Members in a batch”.
.PNG)
- Assurez-vous que les deux menus déroulants soient sur les valeurs “Production” et “Raw”.
- Cliquez sur le bouton intitulé “Show JSON Schema” qui apparaîtra sous le bouton “Try”. S'il n'y est pas, rafraîchissez simplement la page (F5) pour voir apparaître l'icône.
.PNG)
Vous devriez obtenir ceci :
Étape 3 : Comparer les schémas
Maintenant que nous avons tout le nécessaire, naviguons jusqu’à la page d’un valideur de schéma en ligne de votre choix.
Dans cet exemple, nous avons choisi d’utiliser https://www.jsonschemavalidator.net/ parce que celui-ci détecte automatiquement la version du schéma, mais il y a d'autres outils de disponible comme JSON Schema Lint.
Malheureusement, la plupart de ces outils sont disponibles uniquement en anglais.
Pour utiliser le valideur, suivez ces étapes :
- Naviguez jusqu’à la page suivante https://www.jsonschemavalidator.net/
- Copiez et collez notre schéma JSON (que vous avez récupéré à l'étape précédente) dans la zone de texte de gauche.
- Copiez et collez votre structure de données JSON dans la zone de texte de droite.
- L'outil procédera par la suite à la comparaison des deux structures et les erreurs seront indiquées par un x rouge. Il ne vous restera plus qu'à corriger, par la suite, votre schéma.
Exemple de schéma JSON erroné
Vous pourrez voir ci-dessous que le valideur a réussi à trouver deux erreurs.
En survolant avec le pointeur de votre souris les x rouges (par exemple, voir le x à la droite de la ligne #3 dans la partie de droite de l'image ci-haut), vous pourrez voir la cause de l'erreur. Ici, la première erreur est causée par la ligne “relationType” qui aurait un problème de “Invalid type. Expected String but got Integer”, ce qui peut être traduit en français par “Type invalide, une chaîne de caractères était attendue, mais c'est plutôt un nombre entier qui a été obtenu”.
Pour corriger l'erreur, nous allons tenter de remplacer l’entier 28 par une chaîne de caractères, telle que “this is a string”. Voici le résultat suite à la correction :
On remarque immédiatement que nous avons encore une erreur à la ligne #3, mais qu’il s’agit maintenant d’une autre erreur.
- Value “this is a string” is not defined in enum
- ce qui peut être traduit en français par : “this is a string” n’est pas une valeure définie dans l’énum
"relationType": {
"type": "string",
"enum": [
"express-consent",
"active-clients",
"information-request",
"business-card",
"web-contacts",
"purchased-list",
"contest-participants",
"mixed-list",
"inactive-clients",
"association-members",
"employees",
"partners"
]
}
Remplacez ensuite “this is a string” par une des valeurs qui se trouve dans l’énum, comme “active-clients” :
.png)
Le crochet vert au bas de l'image indique qu'il n'y a maintenant plus d'erreur avec le schéma.
Vous pouvez aussi remarquer que notre deuxième erreur n’est plus là elle non plus. Cela signifie que cette erreur était causée par la première erreur que nous venons de résoudre.
En effet, dans bien des cas, les erreurs de validation de schéma JSON qui semblent les plus complexes sont souvent les conséquences d’autres erreurs plus simples. Ainsi, il est bien lorsqu’on tente de diagnostiquer des erreurs de validation de schéma, de commencer par les erreurs qui nous semblent les plus simples à corriger en premier.
À moins que vos structures de donnée JSON contiennent une grande quantité d’erreurs, suivre les étapes de cette procédure de diagnostic devrait, au moins, vous mettre sur la bonne piste pour les résoudre.