4. 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 à 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 ; au contraire, ils sont 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 considérer 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 potentiellement s'appliquer à n'importe quelle ressource sur le Web -- sont généralement mieux exprimés comme des codes d'état simples. Par exemple, un problème « accès en écriture interdit » est probablement inutile, puisqu'un code d'état 403 Forbidden en réponse à une requête PUT est explicite.

Enfin, une application peut avoir un moyen plus approprié 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 documents « fault » ou « error », et non à remplacer les formats spécifiques au domaine existants.

Cela dit, il est possible d'ajouter un support pour les 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 [RFC7231], Section 5.3.2).

Les nouvelles définitions de types de problèmes doivent (MUST) documenter :

1. un URI de type (généralement, avec le schéma « http » ou « https »),

2. un title qui le décrit de manière appropriée (pensez court), et

3. le code d'état HTTP avec lequel il sera utilisé.

Les définitions de types de problèmes peuvent (MAY) spécifier l'utilisation de l'en-tête de réponse Retry-After ([RFC7231], Section 7.1.3) dans des circonstances appropriées.

L'URI de type d'un problème devrait (SHOULD) se résoudre en documentation HTML [W3C.REC-html5-20141028] qui explique comment résoudre le problème.

Une définition de type de problème peut (MAY) 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 [RFC5988] vers une autre ressource qui peut être utilisée par les machines pour résoudre le problème.

Si de tels membres supplémentaires sont définis, leurs noms devraient (SHOULD) commencer par une lettre (ALPHA, selon [RFC5234], Appendix B.1) et devraient (SHOULD) se composer de caractères de ALPHA, DIGIT ([RFC5234], Appendix B.1), et « _ » (afin qu'il puisse être sérialisé dans des formats autres que JSON), et ils devraient (SHOULD) avoir trois caractères ou plus.

4.1. Exemple (Example)

Par exemple, si vous publiez une API HTTP pour votre panier d'achat en ligne, vous pourriez avoir besoin d'indiquer que l'utilisateur manque 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 accueillir ces informations, c'est probablement préférable. Cependant, si vous n'en avez pas, vous pourriez envisager d'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 un URI de type déjà défini qui convient à vos objectifs. Si 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 title approprié et le code d'état HTTP avec lequel il sera utilisé, ainsi que ce qu'il signifie et comment il doit être géré.

En résumé : un URI d'instance identifiera toujours une occurrence spécifique d'un problème. D'autre part, les URI de type peuvent être réutilisés si une description appropriée d'un type de problème est déjà disponible ailleurs, ou ils peuvent être créés pour de nouveaux types de problèmes.

4.2. Types de problèmes prédéfinis (Predefined Problem Types)

Cette spécification réserve l'utilisation d'un URI comme type de problème :

L'URI about:blank [RFC6694], 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 d'état HTTP.

Lorsque about:blank est utilisé, le title devrait (SHOULD) ê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 (MAY) être localisé pour s'adapter 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.

---