1. Introduction
Les codes d'état HTTP [RFC7230] ne sont parfois pas suffisants pour transmettre suffisamment d'informations sur une erreur pour être utiles. Alors que les humains derrière les navigateurs Web peuvent être informés de la nature du problème avec un corps de réponse HTML [W3C.REC-html5-20141028], les consommateurs non humains des soi-disant « API HTTP » ne le sont généralement pas.
Cette spécification définit des formats de documents JSON [RFC7159] et XML [W3C.REC-xml-20081126] simples pour répondre à cet objectif. Ils sont conçus pour être réutilisés par les API HTTP, qui peuvent identifier des « types de problèmes (Problem Types) » distincts spécifiques à leurs besoins.
Ainsi, les clients d'API peuvent être informés à la fois de la classe d'erreur de haut niveau (en utilisant le code d'état) et des détails plus fins du problème (en utilisant l'un de ces formats).
Par exemple, considérons une réponse qui indique que le compte du client n'a pas assez de crédit. Le code d'état 403 Forbidden pourrait être jugé le plus approprié à utiliser, car il informera les logiciels HTTP génériques (tels que les bibliothèques clientes, les caches et les proxies) de la sémantique générale de la réponse.
Cependant, cela ne donne pas au client d'API suffisamment d'informations sur pourquoi la requête a été interdite, le solde du compte applicable, ou comment corriger le problème. Si ces détails sont inclus dans le corps de la réponse dans un format lisible par machine, le client peut le traiter de manière appropriée ; par exemple, en déclenchant un transfert de crédit supplémentaire sur le compte.
Cette spécification le fait en identifiant un type spécifique de problème (par exemple, « manque de crédit (out of credit) ») avec un URI [RFC3986] ; les API HTTP peuvent le faire en désignant de nouveaux URI sous leur contrôle, ou en réutilisant ceux existants.
De plus, les détails du problème peuvent contenir d'autres informations, telles qu'un URI qui identifie 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'investigation.
Le modèle de données pour les détails de problème est un objet JSON [RFC7159] ; lorsqu'il est formaté comme un document JSON, il utilise le type de média application/problem+json. L'annexe A définit comment les exprimer dans un format XML équivalent, qui utilise le type de média application/problem+xml.
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 d'accommoder la description des détails pertinents dans le format de cette application. De même, dans de nombreuses situations, il existe un code d'état HTTP approprié qui ne nécessite pas de détail supplémentaire à transmettre.
Au lieu de cela, 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 d'état HTTP existants. Même si une application choisit de ne pas l'utiliser pour transmettre des erreurs, l'examen de sa conception peut aider à guider les décisions de conception rencontrées lors de la transmission d'erreurs dans un format existant.