1. Introduction
Les codes de statut HTTP (section 15 de [HTTP]) ne peuvent pas toujours transmettre suffisamment d'informations sur les erreurs pour être utiles. Alors que les humains utilisant des navigateurs web peuvent souvent comprendre un contenu de réponse HTML [HTML5], les consommateurs non humains des API HTTP ont des difficultés à le faire.
Pour remédier à cette lacune, cette spécification définit des formats de documents JSON [JSON] et XML [XML] simples pour décrire les spécificités d'un problème rencontré -- "détails de problème" (problem details).
Par exemple, considérons une réponse indiquant que le compte du client n'a pas assez de crédit. Le concepteur de l'API pourrait décider d'utiliser le code de statut 403 Forbidden pour informer le logiciel HTTP générique (tel que les bibliothèques clientes, les caches et les proxies) de la sémantique générale de la réponse. Les détails de problème spécifiques à l'API (tels que la raison pour laquelle le serveur a refusé la requête et le solde de compte applicable) peuvent être transportés dans le contenu de réponse afin que le client puisse agir de manière appropriée (par exemple, déclencher un transfert de plus de crédit vers le compte).
Cette spécification identifie le "type de problème" (problem type) spécifique (par exemple, "out of credit") avec un URI [URI]. Les API HTTP peuvent utiliser des URI sous leur contrôle pour identifier les problèmes qui leur sont spécifiques ou peuvent réutiliser des URI existants pour faciliter l'interopérabilité et tirer parti de la sémantique commune (voir section 4.2).
Les détails de problème peuvent contenir d'autres informations, telles qu'un URI identifiant l'occurrence spécifique du problème (donnant effectivement un identifiant au concept "Le moment où Joe n'avait pas assez de crédit jeudi dernier"), ce qui peut être utile à des fins de support ou d'analyse forensique.
Le modèle de données pour les détails de problème est un objet JSON [JSON]; lorsqu'il est sérialisé en tant que document JSON, il utilise le type de média "application/problem+json". L'annexe B définit un format XML équivalent, qui utilise le type de média "application/problem+xml".
Lorsqu'ils sont transmis dans une réponse HTTP, le contenu des détails de problème peut être négocié en utilisant la négociation proactive; voir section 12.1 de [HTTP]. En particulier, la langue utilisée pour les chaînes lisibles par l'homme (telles que celles dans title et description) peut être négociée en utilisant le champ d'en-tête de requête Accept-Language (section 12.5.4 de [HTTP]), bien que cette négociation puisse encore aboutir au retour d'une représentation par défaut non préférée.
Les détails de problème peuvent être utilisés avec n'importe quel code de statut HTTP, mais ils correspondent le plus naturellement à la sémantique des réponses 4xx et 5xx. Notez que les détails de problème ne sont (naturellement) pas le seul moyen de transmettre les détails d'un problème en HTTP. Si la réponse est toujours une représentation d'une ressource, par exemple, il est souvent préférable de décrire les détails pertinents dans le format de cette application. De même, les codes de statut HTTP définis couvrent de nombreuses situations sans nécessiter de transmettre des détails supplémentaires.
L'objectif de cette spécification est de définir des formats d'erreur communs pour les applications qui en ont besoin afin qu'elles ne soient pas obligées de définir les leurs ou, pire, tentées de redéfinir la sémantique des codes de statut HTTP existants. Même si une application choisit de ne pas l'utiliser pour transmettre des erreurs, examiner sa conception peut aider à guider les décisions de conception rencontrées lors de la transmission d'erreurs dans un format existant.
Voir l'annexe D pour une liste des changements par rapport à [RFC7807].