4. Defining New Problem Types (Definizione di nuovi tipi di problema)
Quando un'API HTTP deve definire una risposta che indica una condizione di errore, può 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; sono piuttosto un mezzo per esporre più dettagli sull'interfaccia HTTP stessa. I progettisti di nuovi tipi di problema dovrebbero considerare attentamente le considerazioni sulla sicurezza (sezione 5), in particolare il rischio di esporre vettori di attacco esponendo dettagli interni dell'implementazione attraverso messaggi di errore.
Allo stesso modo, i problemi veramente generici -- cioè, condizioni che potrebbero applicarsi a qualsiasi risorsa sul Web -- sono generalmente meglio espressi come semplici codici di stato. Ad esempio, un problema "write access disallowed" è 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 per trasportare un errore in un formato che definisce già. I dettagli del problema sono destinati a evitare la necessità di stabilire nuovi formati di documento "fault" o "error", non a sostituire formati specifici del dominio esistenti.
Detto questo, è possibile aggiungere supporto per i dettagli del problema alle API HTTP esistenti utilizzando la negoziazione del contenuto HTTP (ad es., utilizzando l'intestazione di richiesta Accept per indicare una preferenza per questo formato; vedere sezione 12.5.1 di [HTTP]).
Le nuove definizioni di tipi di problema DEVONO documentare:
-
un URI di tipo (tipicamente, con lo schema "http" o "https")
-
un titolo che lo descriva in modo appropriato (pensate breve)
-
il codice di stato HTTP con cui dovrebbe essere utilizzato
Le definizioni dei tipi di problema POSSONO specificare l'uso dell'intestazione di risposta Retry-After (sezione 10.2.3 di [HTTP]) in circostanze appropriate.
Un URI di tipo di problema DOVREBBE risolversi in documentazione HTML [HTML5] che spiega come risolvere il problema.
Una definizione di tipo di problema PUÒ specificare membri aggiuntivi sull'oggetto di dettagli del problema. Ad esempio, un'estensione potrebbe utilizzare link tipizzati [WEB-LINKING] a un'altra risorsa che le macchine possono utilizzare per risolvere il problema.
Se tali membri aggiuntivi sono definiti, i loro nomi DOVREBBERO iniziare con una lettera (ALPHA, secondo [ABNF], appendice B.1) e DOVREBBERO comprendere caratteri da ALPHA, DIGIT ([ABNF], appendice B.1) e "_" (in modo che possano essere serializzati in formati diversi da JSON), e DOVREBBERO avere tre caratteri o più.
4.1. Example (Esempio)
Ad esempio, se state pubblicando un'API HTTP per il vostro carrello della spesa online, potreste dover indicare che l'utente non ha abbastanza credito (il nostro esempio sopra) e quindi non può effettuare l'acquisto.
Se avete già un formato specifico dell'applicazione che può accogliere queste informazioni, è probabilmente meglio farlo. Tuttavia, se non lo avete, potreste 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 nel registro (sezione 4.2) un URI di tipo già definito che si adatta alle vostre esigenze. Se ne è disponibile uno, potete riutilizzare quell'URI.
Se nessuno è disponibile, potreste creare e documentare un nuovo URI di tipo (che dovrebbe essere sotto il vostro controllo e stabile nel tempo), un titolo appropriato e il codice di stato HTTP con cui sarà utilizzato, nonché cosa significa e come dovrebbe essere trattato.
4.2. Registered Problem Types (Tipi di problema registrati)
Questa specifica definisce il registro "HTTP Problem Types" per URI di tipi di problema comuni e ampiamente utilizzati, per promuovere il riutilizzo.
La politica per questo registro è Specification Required, secondo [RFC8126], sezione 4.6.
Quando si valutano le richieste, l'esperto/gli esperti designato/i dovrebbe/dovrebbero considerare il feedback della comunità, quanto bene è definito il tipo di problema e i requisiti di questa specifica. I valori specifici del fornitore, specifici dell'applicazione e specifici della distribuzione non possono essere registrati. I documenti di specifica devono essere pubblicati in modo stabile e liberamente disponibile (idealmente localizzati con un URL) ma non devono necessariamente essere standard.
Le registrazioni POSSONO utilizzare il prefisso "https://iana.org/assignments/http-problem-types#" per l'URI di tipo. Si noti che questi URI potrebbero non essere risolvibili.
Il seguente modello dovrebbe essere utilizzato per le richieste di registrazione:
Type URI: [un URI per il tipo di problema]
Title: [una breve descrizione del tipo di problema]
Recommended HTTP status code: [quale codice di stato è più appropriato da utilizzare con il tipo]
Reference: [a una specifica che definisce il tipo]
Vedere il registro su https://iana.org/assignments/http-problem-types per i dettagli su dove inviare le richieste di registrazione.
4.2.1. about:blank
Questa specifica registra un tipo di problema, "about:blank", come segue.
Type URI: about:blank
Title: See HTTP Status Code
Recommended HTTP status code: N/A
Reference: RFC 9457
L'URI "about:blank" [ABOUT], 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 titolo DOVREBBE essere lo stesso della frase di stato HTTP raccomandata per quel codice (ad es., "Not Found" per 404, e così via), anche se PUÒ essere localizzato per adattarsi alle preferenze del client (espresse con l'intestazione di richiesta Accept-Language).
Si prega di notare che secondo come è definito il membro "type" (sezione 3.1), l'URI "about:blank" è il valore predefinito per quel membro. Pertanto, qualsiasi oggetto di dettagli del problema che non porta un membro "type" esplicito utilizza implicitamente questo URI.