Passa al contenuto principale

3. L'oggetto JSON dei dettagli del problema

Il modello canonico per i dettagli del problema è un oggetto JSON [RFC7159].

Quando serializzato come documento JSON, quel formato è identificato con il tipo di media application/problem+json.

Ad esempio, una risposta HTTP che trasporta dettagli di problema JSON:

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
Content-Language: en

{
 "type": "https://example.com/probs/out-of-credit",
 "title": "You do not have enough credit.",
 "detail": "Your current balance is 30, but that costs 50.",
 "instance": "/account/12345/msgs/abc",
 "balance": 30,
 "accounts": ["/account/12345",
              "/account/67890"]
}

Qui, il problema di credito esaurito (identificato dal suo URI di tipo) indica la ragione del 403 in title, fornisce un riferimento per l'occorrenza specifica del problema con instance, fornisce dettagli specifici dell'occorrenza in detail, e aggiunge due estensioni; balance trasmette il saldo del conto, e accounts fornisce link dove il conto può essere ricaricato.

La capacità di trasmettere estensioni specifiche del problema consente di trasmettere più di un problema. Ad esempio:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Language: en

{
"type": "https://example.net/validation-error",
"title": "Your request parameters didn't validate.",
"invalid-params": [ {
                      "name": "age",
                      "reason": "must be a positive integer"
                    },
                    {
                      "name": "color",
                      "reason": "must be 'green', 'red' or 'blue'"}
                  ]
}

Si noti che ciò richiede che ciascuno dei sotto-problemi sia sufficientemente simile da utilizzare lo stesso codice di stato HTTP. Se non lo sono, il codice 207 (Multi-Status) [RFC4918] potrebbe essere utilizzato per incapsulare più messaggi di stato.

3.1. Membri di un oggetto di dettagli del problema (Members of a Problem Details Object)​

Un oggetto di dettagli del problema può avere i seguenti membri:

  • type (stringa) - Un riferimento URI [RFC3986] che identifica il tipo di problema. Questa specifica incoraggia che, quando dereferenziato, fornisca documentazione leggibile dall'uomo per il tipo di problema (ad es., utilizzando HTML [W3C.REC-html5-20141028]). Quando questo membro non è presente, il suo valore è assunto essere about:blank.

  • title (stringa) - Un breve riepilogo leggibile dall'uomo del tipo di problema. Non dovrebbe (SHOULD NOT) cambiare da un'occorrenza all'altra del problema, tranne che per scopi di localizzazione (ad es., utilizzando la negoziazione proattiva del contenuto; vedere [RFC7231], Section 3.4).

  • status (numero) - Il codice di stato HTTP ([RFC7231], Section 6) generato dal server di origine per questa occorrenza del problema.

  • detail (stringa) - Una spiegazione leggibile dall'uomo specifica per questa occorrenza del problema.

  • instance (stringa) - Un riferimento URI che identifica l'occorrenza specifica del problema. Può o non può fornire ulteriori informazioni se dereferenziato.

I consumatori devono (MUST) utilizzare la stringa type come identificatore primario per il tipo di problema; la stringa title è consultiva e inclusa solo per gli utenti che non sono a conoscenza della semantica dell'URI e non hanno la capacità di scoprirli (ad es., analisi dei log offline). I consumatori non dovrebbero (SHOULD NOT) dereferenziare automaticamente l'URI di tipo.

Il membro status, se presente, è solo consultivo; trasmette il codice di stato HTTP utilizzato per comodità del consumatore. I generatori devono (MUST) utilizzare lo stesso codice di stato nella risposta HTTP effettiva, per assicurare che il software HTTP generico che non comprende questo formato si comporti ancora correttamente. Vedere la Sezione 5 per ulteriori avvertenze riguardanti il suo utilizzo.

I consumatori possono utilizzare il membro status per determinare quale fosse il codice di stato originale utilizzato dal generatore, nei casi in cui sia stato modificato (ad es., da un intermediario o cache), e quando i corpi dei messaggi persistono senza informazioni HTTP. Il software HTTP generico utilizzerà comunque il codice di stato HTTP.

Il membro detail, se presente, dovrebbe concentrarsi sull'aiutare il client a correggere il problema, piuttosto che fornire informazioni di debug.

I consumatori non dovrebbero (SHOULD NOT) analizzare il membro detail per informazioni; le estensioni sono modi più adatti e meno soggetti a errori per ottenere tali informazioni.

Si noti che sia type che instance accettano URI relativi; ciò significa che devono essere risolti relativamente all'URI di base del documento, come da [RFC3986], Section 5.

3.2. Membri di estensione (Extension Members)​

Le definizioni di tipi di problema possono (MAY) estendere l'oggetto di dettagli del problema con membri aggiuntivi.

Ad esempio, il nostro problema "credito esaurito" sopra definisce due di tali estensioni -- balance e accounts per trasmettere informazioni aggiuntive specifiche del problema.

I client che consumano dettagli del problema devono (MUST) ignorare qualsiasi estensione che non riconoscono; ciò consente ai tipi di problema di evolversi e includere informazioni aggiuntive in futuro.

Si noti che poiché le estensioni sono effettivamente poste in uno spazio dei nomi dal tipo di problema, non è possibile definire nuovi membri "standard" senza definire un nuovo tipo di media.

Ultimo aggiornamento il