| Les deux révisions précédentesRévision précédenteProchaine révision | Révision précédente |
| serveurscrutari:json:messages [2011/03/21 15:03] – vincent | serveurscrutari:json:messages [2013/04/17 15:06] (Version actuelle) – vincent |
|---|
| ====== Messages d'erreur ====== | ====== Messages d'erreur ====== |
| |
| En cas d'erreur de programmation (par exemple, un paramètre obligatoire manquant), le serveur renvoie un objet JSON particulier appelé « message de commande » qui comprend une clé indiquant l'erreur relevée. Un message de commande peut relever plusieurs erreurs à la fois. | En cas d'erreur de programmation (par exemple, un paramètre obligatoire manquant), le serveur renvoie un objet JSON particulier nommé //error// à la place de l'objet attendu. |
| |
| Les messages d'erreur sont réservés aux bogues du côté client, tout ce qui est susceptible de découler d'une mauvaise saisie de l'utilisateur n'est pas traitée comme erreur. Par exemple, si l'internaute envoie une séquence de recherche composée de caractères non textuels (par exemple, « "'(\ »), le serveur ne va pas envoyer de messages d'erreur mais simplement un résultat vide. En l'occurence, il renverra un objet //ficheSearchResult// avec comme //qLength = 0//. Il revient au client de traiter ce cas et de le signaler à l'internaute. | Une erreur est envoyée si le le serveur est dans l'incapacité de faire le traitement avec les paramètres transmis. Elle est généralement révélatrice d'un bogue côté client mais une erreur peut aussi être due à une mauvaise saisie de l'utilisateur dans le cas de la recherche avancée lorsque l'utilisateur n'a pas respecté la syntaxe, à charge pour le client d'alerter l'utilisateur final sur sa saisie incorrecte. |
| |
| Autrement dit, tout requête est susceptible de renvoyer deux objets différents : l'objet normalement attendu (//ficheSearchResult// dans le cas d'une recherche sur les fiches) ou //commandMessage// en cas d'erreur. Il revient au client de faire un test préalable pour savoir s'il est en présence d'une erreur ou non. | Un paramètre optionnel incorrect (par exemple; //limit// qui n'a pas comme valeur un entier) ne donnera pas lieu à l'envoi d'un message d'erreur car le serveur prend alors la valeur par défaut du paramètre. Ce type d'erreur est signalé au client par les [[serveurscrutari:json:warnings|messages d'avertissement]]. |
| |
| Note : en général, une erreur est envoyée que si elle a lieu sur un paramètre obligatoire. Si elle a lieu sur un paramètre optionnel (par exemple; //limit// qui n'a pas comme valeur un entier), elle est ignoré et c'est la valeur par défaut du paramètre optionnel qui est traité par le serveur. | Une erreur est composé de trois éléments : une clé indiquant la nature de l'erreur, le paramètre concerné par l'erreur, la valeur de paramètre éventuellement à l'origine de l'erreur. Elle peut également comporte un détail précisant l'erreur sous la forme d'un tableau d'erreurs complémentaires. |
| | |
| | Une erreur peut être complétée par des avertissements s'ils ont eu lieu avant que l'erreur se produise comme indiqué à la page [[serveurscrutari:json:warnings|Messages d'avertissement]]. |
| |
| ===== Clés d'erreur ===== | ===== Clés d'erreur ===== |
| Les erreurs susceptibles d'être rencontrées sont les suivantes : | Les erreurs susceptibles d'être rencontrées sont les suivantes : |
| |
| * //missingTypeParameter// : le paramètre //type// n'est pas défini, le serveur ne peut pas comprendre quelle requête est demandée | * //missingParameter// : le paramètre indiqué est absent alors qu'il est obligatoire |
| * //emptyTypeParameter// : le paramètre //type// existe mais est vide | * //emptyParameter// : le paramètre indiqué est présent mais vide |
| * //wrongTypeParameter// : la valeur du paramètre type est incorrecte, cette valeur est rappelée dans la propriété //text// du message d'erreur | * //malformedParameterValue// : la forme du paramètre est incorrecte (par exemple, un mauvais code de langue) |
| * //missingModeParameter// : le paramètre //mode// n'est pas défini ([[serveurscrutari:json:type_fiche|type=fiche]]) | * //unknownParameterValue// : la valeur pour le paramètre indiqué est inconnue, cela arrive pour les paramètres dont les valeurs possibles sont fixées (par exemple, les paramètres //type// et //mode//) ou s'ils sont censés identifier une ressource particulière (par exemple, //q-id//) |
| * //emptyModeParameter// : le paramètre //mode// est présent mais vide ([[serveurscrutari:json:type_fiche|type=fiche]]) | * //badOperationSyntax// : la syntaxe de l'opération de recherche est incorrecte (cas des recherches avancées) |
| * //wrongModeParameter// : la valeur du paramètre //mode// est incorrecte, cette valeur est rappelée dans la propriété //text// du message d'erreur ([[serveurscrutari:json:type_fiche|type=fiche]]) | |
| * //missingQFicheParameters// : les paramètres obligatoires //q// et //q-id// (mutellement exclusifs) sont absents dans la recherche de fiches ([[serveurscrutari:json:type_qfiche|type=q-fiche]]) | |
| * //emptyQIdParameter// : paramètre //q-id// présent mais vide ([[serveurscrutari:json:type_qfiche|type=q-fiche]]) | |
| * //wrongQIdParameter// : l'identifiant donné par le paramètre //q-id// est incorrect car ne correspond pas à une requête enregistrée , cette valeur est rappelée dans la propriété //text// du message d'erreur([[serveurscrutari:json:type_qfiche|type=q-fiche]]) | |
| |
| |
| <code javascript> | <code javascript> |
| { | { |
| commandMessage: { | error: { |
| type: 'error', //à l'heure actuelle, la valeur est toujours 'error' | key: … , // clé de l'erreur (chaine) |
| key: … , // clé identifiant l'erreur (chaine) | parameter: … , // paramètre source de l'erreur (chaine) |
| text: … , // texte optionnel décrivant l'erreur | value: … , // valeur de paramètre à l'origine de l'erreur (optionnel, chaine) |
| array: [ // en cas d'erreur multiple, tableau avec la liste des erreurs rencontrées, optionnel | array: [//tableau des erreurs détaillant l'erreur principale |
| { // chaque erreur est objet | { // chaque erreur est un objet |
| key: … , // clé identifiant l'erreur (chaine) | key: … , // clé de l'erreur (chaine) |
| text: … , // texte optionnel décrivant l'erreur | value: … // valeur à l'origine de l'erreur (optionnel, chaine) |
| }, | } |
| ... | |
| ] | ] |
| } | } |
| | } |
| </code> | </code> |
| |
