1. Introduzione
I codici di stato HTTP [RFC7230] a volte non sono sufficienti per trasmettere abbastanza informazioni su un errore per essere utili. Mentre gli esseri umani dietro i browser Web possono essere informati sulla natura del problema con un corpo di risposta HTML [W3C.REC-html5-20141028], i consumatori non umani delle cosiddette "API HTTP" di solito non lo sono.
Questa specifica definisce formati di documenti JSON [RFC7159] e XML [W3C.REC-xml-20081126] semplici per questo scopo. Sono progettati per essere riutilizzati dalle API HTTP, che possono identificare "tipi di problema (Problem Types)" distinti specifici per le loro esigenze.
Pertanto, i client API possono essere informati sia della classe di errore di alto livello (utilizzando il codice di stato) sia dei dettagli più granulari del problema (utilizzando uno di questi formati).
Ad esempio, si consideri una risposta che indica che l'account del client non ha credito sufficiente. Il codice di stato 403 Forbidden potrebbe essere ritenuto il più appropriato da utilizzare, poiché informerà il software HTTP generico (come librerie client, cache e proxy) della semantica generale della risposta.
Tuttavia, ciò non fornisce al client API informazioni sufficienti sul motivo per cui la richiesta è stata vietata, sul saldo dell'account applicabile o su come correggere il problema. Se questi dettagli sono inclusi nel corpo della risposta in un formato leggibile dalle macchine, il client può trattarlo in modo appropriato; ad esempio, attivando un trasferimento di più credito nell'account.
Questa specifica lo fa identificando un tipo specifico di problema (ad es., "credito esaurito (out of credit)") con un URI [RFC3986]; le API HTTP possono farlo nominando nuovi URI sotto il loro controllo o riutilizzando quelli esistenti.
Inoltre, i dettagli del problema possono contenere altre informazioni, come un URI che identifica l'occorrenza specifica del problema (dando effettivamente un identificatore al concetto "Il momento in cui Joe non aveva abbastanza credito giovedì scorso"), che può essere utile per scopi di supporto o forensi.
Il modello dati per i dettagli del problema è un oggetto JSON [RFC7159]; quando formattato come documento JSON, utilizza il tipo di media application/problem+json. L'Appendice A definisce come esprimerli in un formato XML equivalente, che utilizza il tipo di media application/problem+xml.
Si noti che i dettagli del problema (naturalmente) non sono l'unico modo per trasmettere i dettagli di un problema in HTTP; se la risposta è ancora una rappresentazione di una risorsa, ad esempio, è spesso preferibile accogliere la descrizione dei dettagli rilevanti nel formato di quell'applicazione. Allo stesso modo, in molte situazioni, esiste un codice di stato HTTP appropriato che non richiede la trasmissione di dettagli extra.
Invece, l'obiettivo di questa specifica è definire formati di errore comuni per quelle applicazioni che ne hanno bisogno, in modo che non siano obbligate a definire i propri o, peggio, tentate di ridefinire la semantica dei codici di stato HTTP esistenti. Anche se un'applicazione sceglie di non usarlo per trasmettere errori, rivedere il suo design può aiutare a guidare le decisioni di progettazione affrontate quando si trasmettono errori in un formato esistente.