4. Defining New Problem Types (Définition de nouveaux types de problèmes)
Lorsqu'une API HTTP doit définir une réponse qui indique une condition d'erreur, il peut être approprié de le faire en définissant un nouveau type de problème.
Avant de le faire, il est important de comprendre pour quoi ils sont bons et ce qui est mieux laissé à d'autres mécanismes.
Les détails de problème ne sont pas un outil de débogage pour l'implémentation sous-jacente; ils sont plutôt un moyen d'exposer plus de détails sur l'interface HTTP elle-même. Les concepteurs de nouveaux types de problèmes doivent soigneusement prendre en compte les considérations de sécurité (section 5), en particulier, le risque d'exposer des vecteurs d'attaque en exposant les détails internes de l'implémentation à travers les messages d'erreur.
De même, les problèmes vraiment génériques -- c'est-à-dire les conditions qui pourraient s'appliquer à n'importe quelle ressource sur le Web -- sont généralement mieux exprimés en tant que codes de statut simples. Par exemple, un problème "write access disallowed" est probablement inutile, puisqu'un code de statut 403 Forbidden en réponse à une requête PUT est auto-explicatif.
Enfin, une application pourrait avoir une façon plus appropriée de transporter une erreur dans un format qu'elle définit déjà. Les détails de problème sont destinés à éviter la nécessité d'établir de nouveaux formats de document "fault" ou "error", pas à remplacer les formats spécifiques au domaine existants.
Cela dit, il est possible d'ajouter le support des détails de problème aux API HTTP existantes en utilisant la négociation de contenu HTTP (par exemple, en utilisant l'en-tête de requête Accept pour indiquer une préférence pour ce format; voir section 12.5.1 de [HTTP]).
Les nouvelles définitions de types de problèmes DOIVENT documenter:
-
un URI de type (généralement, avec le schéma "http" ou "https")
-
un titre qui le décrit de manière appropriée (pensez court)
-
le code de statut HTTP avec lequel il doit être utilisé
Les définitions de types de problèmes PEUVENT spécifier l'utilisation de l'en-tête de réponse Retry-After (section 10.2.3 de [HTTP]) dans des circonstances appropriées.
Un URI de type de problème DEVRAIT résoudre en documentation HTML [HTML5] qui explique comment résoudre le problème.
Une définition de type de problème PEUT spécifier des membres supplémentaires sur l'objet de détails de problème. Par exemple, une extension pourrait utiliser des liens typés [WEB-LINKING] vers une autre ressource que les machines peuvent utiliser pour résoudre le problème.
Si de tels membres supplémentaires sont définis, leurs noms DEVRAIENT commencer par une lettre (ALPHA, selon [ABNF], annexe B.1) et DEVRAIENT comprendre des caractères de ALPHA, DIGIT ([ABNF], annexe B.1), et "_" (de sorte qu'ils puissent être sérialisés dans des formats autres que JSON), et ils DEVRAIENT avoir trois caractères ou plus.
4.1. Example (Exemple)
Par exemple, si vous publiez une API HTTP pour votre panier d'achat en ligne, vous pourriez avoir besoin d'indiquer que l'utilisateur n'a pas assez de crédit (notre exemple ci-dessus) et ne peut donc pas effectuer l'achat.
Si vous avez déjà un format spécifique à l'application qui peut accommoder ces informations, il est probablement préférable de faire cela. Cependant, si vous ne l'avez pas, vous pourriez utiliser l'un des formats de détails de problème -- JSON si votre API est basée sur JSON ou XML si elle utilise ce format.
Pour ce faire, vous pourriez chercher dans le registre (section 4.2) un URI de type déjà défini qui convient à vos besoins. Si l'un est disponible, vous pouvez réutiliser cet URI.
Si aucun n'est disponible, vous pourriez créer et documenter un nouvel URI de type (qui devrait être sous votre contrôle et stable dans le temps), un titre approprié et le code de statut HTTP avec lequel il sera utilisé, ainsi que ce qu'il signifie et comment il doit être traité.
4.2. Registered Problem Types (Types de problèmes enregistrés)
Cette spécification définit le registre "HTTP Problem Types" pour les URI de types de problèmes communs et largement utilisés, afin de promouvoir la réutilisation.
La politique pour ce registre est Specification Required, selon [RFC8126], section 4.6.
Lors de l'évaluation des demandes, le(s) expert(s) désigné(s) devrait(ent) considérer les commentaires de la communauté, à quel point le type de problème est bien défini, et les exigences de cette spécification. Les valeurs spécifiques au fournisseur, spécifiques à l'application et spécifiques au déploiement ne peuvent pas être enregistrées. Les documents de spécification doivent être publiés de manière stable et librement disponible (idéalement localisés avec une URL) mais ne doivent pas nécessairement être des standards.
Les enregistrements PEUVENT utiliser le préfixe "https://iana.org/assignments/http-problem-types#" pour l'URI de type. Notez que ces URI peuvent ne pas pouvoir être résolus.
Le modèle suivant devrait être utilisé pour les demandes d'enregistrement:
Type URI: [un URI pour le type de problème]
Title: [une brève description du type de problème]
Recommended HTTP status code: [quel code de statut est le plus approprié à utiliser avec le type]
Reference: [à une spécification définissant le type]
Voir le registre à https://iana.org/assignments/http-problem-types pour plus de détails sur l'endroit où envoyer les demandes d'enregistrement.
4.2.1. about:blank
Cette spécification enregistre un type de problème, "about:blank", comme suit.
Type URI: about:blank
Title: See HTTP Status Code
Recommended HTTP status code: N/A
Reference: RFC 9457
L'URI "about:blank" [ABOUT], lorsqu'il est utilisé comme type de problème, indique que le problème n'a pas de sémantique supplémentaire au-delà de celle du code de statut HTTP.
Lorsque "about:blank" est utilisé, le titre DEVRAIT être le même que la phrase de statut HTTP recommandée pour ce code (par exemple, "Not Found" pour 404, et ainsi de suite), bien qu'il PUISSE être localisé pour convenir aux préférences du client (exprimées avec l'en-tête de requête Accept-Language).
Veuillez noter que selon la façon dont le membre "type" est défini (section 3.1), l'URI "about:blank" est la valeur par défaut pour ce membre. Par conséquent, tout objet de détails de problème ne portant pas de membre "type" explicite utilise implicitement cet URI.