4. Definizione di nuovi tipi di problema
Quando un'API HTTP deve definire una risposta che indica una condizione di errore, potrebbe essere appropriato farlo definendo un nuovo tipo di problema.
Prima di farlo, è importante capire per cosa sono buoni e cosa è meglio lasciare ad altri meccanismi.
I dettagli del problema non sono uno strumento di debug per l'implementazione sottostante; piuttosto, sono un modo per esporre maggiori dettagli sull'interfaccia HTTP stessa. I progettisti di nuovi tipi di problema devono considerare attentamente le considerazioni sulla sicurezza (Sezione 5), in particolare, il rischio di esporre vettori di attacco esponendo i dettagli interni dell'implementazione attraverso i messaggi di errore.
Allo stesso modo, i problemi veramente generici -- cioè le condizioni che potrebbero potenzialmente applicarsi a qualsiasi risorsa sul Web -- sono solitamente meglio espressi come semplici codici di stato. Ad esempio, un problema "accesso in scrittura non consentito" è probabilmente inutile, poiché un codice di stato 403 Forbidden in risposta a una richiesta PUT è autoesplicativo.
Infine, un'applicazione potrebbe avere un modo più appropriato di trasportare un errore in un formato che già definisce. I dettagli del problema sono destinati a evitare la necessità di stabilire nuovi formati di documenti "fault" o "error", non a sostituire i formati specifici del dominio esistenti.
Detto ciò, è possibile aggiungere supporto per i dettagli del problema alle API HTTP esistenti utilizzando la negoziazione del contenuto HTTP (ad esempio, utilizzando l'intestazione di richiesta Accept per indicare una preferenza per questo formato; vedere [RFC7231], Section 5.3.2).
Le nuove definizioni di tipo di problema devono (MUST) documentare:
-
un URI di tipo (tipicamente, con lo schema "http" o "https"),
-
un title che lo descriva appropriatamente (pensate breve), e
-
il codice di stato HTTP con cui sarà utilizzato.
Le definizioni di tipo di problema possono (MAY) specificare l'uso dell'intestazione di risposta Retry-After ([RFC7231], Section 7.1.3) in circostanze appropriate.
L'URI di tipo di un problema dovrebbe (SHOULD) risolversi in documentazione HTML [W3C.REC-html5-20141028] che spiega come risolvere il problema.
Una definizione di tipo di problema può (MAY) specificare membri aggiuntivi sull'oggetto di dettagli del problema. Ad esempio, un'estensione potrebbe utilizzare link tipizzati [RFC5988] a un'altra risorsa che può essere utilizzata dalle macchine per risolvere il problema.
Se tali membri aggiuntivi sono definiti, i loro nomi dovrebbero (SHOULD) iniziare con una lettera (ALPHA, secondo [RFC5234], Appendix B.1) e dovrebbero (SHOULD) consistere di caratteri da ALPHA, DIGIT ([RFC5234], Appendix B.1), e "_" (in modo che possa essere serializzato in formati diversi da JSON), e dovrebbero (SHOULD) essere di tre caratteri o più.
4.1. Esempio (Example)
Ad esempio, se state pubblicando un'API HTTP per il vostro carrello della spesa online, potreste dover indicare che l'utente ha esaurito il credito (il nostro esempio sopra), e quindi non può effettuare l'acquisto.
Se avete già un formato specifico dell'applicazione che può ospitare queste informazioni, probabilmente è meglio farlo. Tuttavia, se non lo avete, potreste considerare di utilizzare uno dei formati di dettagli del problema -- JSON se la vostra API è basata su JSON, o XML se utilizza quel formato.
Per farlo, potreste cercare un URI di tipo già definito che si adatti ai vostri scopi. Se uno è disponibile, potete riutilizzare quell'URI.
Se uno non è disponibile, potreste coniare e documentare un nuovo URI di tipo (che dovrebbe essere sotto il vostro controllo e stabile nel tempo), un title appropriato e il codice di stato HTTP con cui sarà utilizzato, insieme a cosa significa e come dovrebbe essere gestito.
In sintesi: un URI di istanza identificherà sempre un'occorrenza specifica di un problema. D'altra parte, gli URI di tipo possono essere riutilizzati se una descrizione appropriata di un tipo di problema è già disponibile da qualche altra parte, oppure possono essere creati per nuovi tipi di problema.
4.2. Tipi di problema predefiniti (Predefined Problem Types)
Questa specifica riserva l'uso di un URI come tipo di problema:
L'URI about:blank [RFC6694], quando utilizzato come tipo di problema, indica che il problema non ha semantica aggiuntiva oltre a quella del codice di stato HTTP.
Quando viene utilizzato about:blank, il title dovrebbe (SHOULD) essere lo stesso della frase di stato HTTP raccomandata per quel codice (ad es., "Not Found" per 404, e così via), anche se può (MAY) essere localizzato per adattarsi alle preferenze del client (espresse con l'intestazione di richiesta Accept-Language).
Si noti che secondo come è definito il membro "type" (Sezione 3.1), l'URI about:blank è il valore predefinito per quel membro. Di conseguenza, qualsiasi oggetto di dettagli del problema che non porta un membro "type" esplicito utilizza implicitamente questo URI.