1. Introduction (Introduzione)

I codici di stato HTTP (sezione 15 di [HTTP]) non possono sempre trasmettere informazioni sufficienti sugli errori per essere utili. Mentre gli esseri umani che utilizzano browser web possono spesso comprendere un contenuto di risposta HTML [HTML5], i consumatori non umani delle API HTTP hanno difficoltà a farlo.

Per affrontare tale carenza, questa specifica definisce semplici formati di documento JSON [JSON] e XML [XML] per descrivere le specifiche di un problema riscontrato -- "dettagli di problema" (problem details).

Ad esempio, si consideri una risposta che indica che l'account del client non ha credito sufficiente. Il progettista dell'API potrebbe decidere di utilizzare il codice di stato 403 Forbidden per informare il software HTTP generico (come librerie client, cache e proxy) della semantica generale della risposta. I dettagli di problema specifici dell'API (come il motivo per cui il server ha rifiutato la richiesta e il saldo dell'account applicabile) possono essere trasportati nel contenuto della risposta in modo che il client possa agire di conseguenza (ad esempio, attivando un trasferimento di più credito nell'account).

Questa specifica identifica il "tipo di problema" (problem type) specifico (ad esempio, "out of credit") con un URI [URI]. Le API HTTP possono utilizzare URI sotto il loro controllo per identificare problemi specifici per loro o possono riutilizzare URI esistenti per facilitare l'interoperabilità e sfruttare la semantica comune (vedere sezione 4.2).

I dettagli di problema possono contenere altre informazioni, come un URI che identifica l'occorrenza specifica del problema (fornendo 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 di dati per i dettagli di problema è un oggetto JSON [JSON]; quando serializzato come documento JSON, utilizza il tipo di media "application/problem+json". L'appendice B definisce un formato XML equivalente, che utilizza il tipo di media "application/problem+xml".

Quando vengono trasmessi in una risposta HTTP, il contenuto dei dettagli di problema può essere negoziato utilizzando la negoziazione proattiva; vedere sezione 12.1 di [HTTP]. In particolare, la lingua utilizzata per le stringhe leggibili dall'uomo (come quelle in title e description) può essere negoziata utilizzando il campo di intestazione della richiesta Accept-Language (sezione 12.5.4 di [HTTP]), sebbene tale negoziazione possa comunque risultare nella restituzione di una rappresentazione predefinita non preferita.

I dettagli di problema possono essere utilizzati con qualsiasi codice di stato HTTP, ma si adattano più naturalmente alla semantica delle risposte 4xx e 5xx. Si noti che i dettagli di 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 descrivere i dettagli pertinenti nel formato di quell'applicazione. Allo stesso modo, i codici di stato HTTP definiti coprono molte situazioni senza necessità di trasmettere dettagli aggiuntivi.

L'obiettivo di questa specifica è definire formati di errore comuni per le 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 utilizzarlo per trasmettere errori, esaminare il suo design può aiutare a guidare le decisioni di progettazione affrontate quando si trasmettono errori in un formato esistente.

Vedere l'appendice D per un elenco delle modifiche rispetto a [RFC7807].