3. L'objet JSON de détails du problème

Le modèle canonique pour les détails de problème est un objet JSON [RFC7159].

Lorsqu'il est sérialisé sous forme de document JSON, ce format est identifié par le type de média application/problem+json.

Par exemple, une réponse HTTP contenant des détails de problème JSON :

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
Content-Language: en

{
 "type": "https://example.com/probs/out-of-credit",
 "title": "You do not have enough credit.",
 "detail": "Your current balance is 30, but that costs 50.",
 "instance": "/account/12345/msgs/abc",
 "balance": 30,
 "accounts": ["/account/12345",
              "/account/67890"]
}

Ici, le problème de manque de crédit (identifié par son URI de type) indique la raison du 403 dans title, donne une référence pour l'occurrence spécifique du problème avec instance, fournit des détails spécifiques à l'occurrence dans detail, et ajoute deux extensions ; balance transmet le solde du compte, et accounts fournit des liens où le compte peut être rechargé.

La capacité de transmettre des extensions spécifiques au problème permet de transmettre plus d'un problème. Par exemple :

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Language: en

{
"type": "https://example.net/validation-error",
"title": "Your request parameters didn't validate.",
"invalid-params": [ {
                      "name": "age",
                      "reason": "must be a positive integer"
                    },
                    {
                      "name": "color",
                      "reason": "must be 'green', 'red' or 'blue'"}
                  ]
}

Notez que cela nécessite que chacun des sous-problèmes soit suffisamment similaire pour utiliser le même code d'état HTTP. S'ils ne le sont pas, le code 207 (Multi-Status) [RFC4918] pourrait être utilisé pour encapsuler plusieurs messages d'état.

3.1. Membres d'un objet de détails de problème (Members of a Problem Details Object)

Un objet de détails de problème peut avoir les membres suivants :

• type (chaîne) - Une référence URI [RFC3986] qui identifie le type de problème. Cette spécification encourage que, lorsqu'elle est déréférencée, elle fournisse une documentation lisible par l'homme pour le type de problème (par exemple, en utilisant HTML [W3C.REC-html5-20141028]). Lorsque ce membre n'est pas présent, sa valeur est supposée être about:blank.

• title (chaîne) - Un résumé court et lisible par l'homme du type de problème. Il ne devrait pas (SHOULD NOT) changer d'une occurrence à l'autre du problème, sauf à des fins de localisation (par exemple, en utilisant la négociation de contenu proactive ; voir [RFC7231], Section 3.4).

• status (nombre) - Le code d'état HTTP ([RFC7231], Section 6) généré par le serveur d'origine pour cette occurrence du problème.

• detail (chaîne) - Une explication lisible par l'homme spécifique à cette occurrence du problème.

• instance (chaîne) - Une référence URI qui identifie l'occurrence spécifique du problème. Elle peut ou non fournir des informations supplémentaires si elle est déréférencée.

Les consommateurs doivent (MUST) utiliser la chaîne type comme identifiant principal pour le type de problème ; la chaîne title est consultative et incluse uniquement pour les utilisateurs qui ne connaissent pas la sémantique de l'URI et n'ont pas la capacité de les découvrir (par exemple, analyse de journaux hors ligne). Les consommateurs ne devraient pas (SHOULD NOT) déréférencer automatiquement l'URI de type.

Le membre status, s'il est présent, n'est que consultatif ; il transmet le code d'état HTTP utilisé pour la commodité du consommateur. Les générateurs doivent (MUST) utiliser le même code d'état dans la réponse HTTP réelle, pour s'assurer que le logiciel HTTP générique qui ne comprend pas ce format se comporte toujours correctement. Voir la Section 5 pour d'autres mises en garde concernant son utilisation.

Les consommateurs peuvent utiliser le membre status pour déterminer quel était le code d'état original utilisé par le générateur, dans les cas où il a été modifié (par exemple, par un intermédiaire ou un cache), et lorsque les corps de message persistent sans informations HTTP. Le logiciel HTTP générique utilisera toujours le code d'état HTTP.

Le membre detail, s'il est présent, devrait se concentrer sur l'aide au client pour corriger le problème, plutôt que de fournir des informations de débogage.

Les consommateurs ne devraient pas (SHOULD NOT) analyser le membre detail pour obtenir des informations ; les extensions sont des moyens plus appropriés et moins sujets aux erreurs pour obtenir de telles informations.

Notez que type et instance acceptent tous deux des URI relatifs ; cela signifie qu'ils doivent être résolus par rapport à l'URI de base du document, comme indiqué dans [RFC3986], Section 5.

3.2. Membres d'extension (Extension Members)

Les définitions de types de problèmes peuvent (MAY) étendre l'objet de détails de problème avec des membres supplémentaires.

Par exemple, notre problème « manque de crédit » ci-dessus définit deux de ces extensions -- balance et accounts pour transmettre des informations supplémentaires spécifiques au problème.

Les clients consommant des détails de problème doivent (MUST) ignorer toute extension qu'ils ne reconnaissent pas ; cela permet aux types de problèmes d'évoluer et d'inclure des informations supplémentaires à l'avenir.

Notez que, comme les extensions sont effectivement placées dans un espace de noms par le type de problème, il n'est pas possible de définir de nouveaux membres « standard » sans définir un nouveau type de média.

---