Errore REST API restituire buone pratiche [chiuso]

Sto cercando una guida sulle buone pratiche quando si tratta di restituire errori da un'API REST. Sto lavorando a una nuova API in modo da poter prendere qualsiasi direzione in questo momento. Il mio tipo di contenuto è XML al momento, ma ho intenzione di supportare JSON in futuro.

Ora sto aggiungendo alcuni casi di errore, come ad esempio un client tenta di aggiungere una nuova risorsa ma ha superato la sua quota di archiviazione. Sto già gestendo alcuni casi di errore con codici di stato HTTP (401 per l'autenticazione, 403 per l'autorizzazione e 404 per URI di richieste non valide). Ho esaminato i codici di errore HTTP benedetti, ma nessuno dell'intervallo 400-417 sembra corretto segnalare errori specifici dell'applicazione. Quindi all'inizio sono stato tentato di restituire il mio errore dell'applicazione con 200 OK e un payload XML specifico (cioè. Pagaci di più e otterrai lo spazio di cui hai bisogno!) Ma mi sono fermato a pensarci e sembra insaponato (/ scrollata di spalle per l'orrore). Inoltre mi sembra di dividere le risposte agli errori in casi distinti, poiché alcuni sono guidati dal codice di stato http e altri dal contenuto.

Quindi quali sono le raccomandazioni del settore? Buone pratiche (spiegare perché!) E anche, da un client pov, che tipo di gestione degli errori nell'API REST semplifica la vita del codice client?

Quindi all'inizio sono stato tentato di restituire il mio errore dell'applicazione con 200 OK e un payload XML specifico (cioè. Pagaci di più e otterrai lo spazio di cui hai bisogno!) Ma mi sono fermato a pensarci e sembra insaponato (/ scrollata di spalle per l'orrore).

Non restituirei un 200 a meno che non ci fosse davvero nulla di sbagliato nella richiesta. Da RFC2616 , 200 significa "la richiesta è riuscita".

Se la quota di archiviazione del client è stata superata (per qualsiasi motivo), restituirei un 403 (proibito):

Il server ha compreso la richiesta, ma si rifiuta di soddisfarla. L'autorizzazione non aiuterà e la richiesta NON DOVREBBE essere ripetuta. Se il metodo di richiesta non era HEAD e il server desidera rendere pubblico il motivo per cui la richiesta non è stata soddisfatta, DOVREBBE descrivere il motivo del rifiuto nell'entità. Se il server non desidera rendere disponibili queste informazioni al client, è possibile utilizzare invece il codice di stato 404 (Not Found).

Questo dice al client che la richiesta era OK, ma che non è riuscita (qualcosa che un 200 non fa). Questo ti dà anche l'opportunità di spiegare il problema (e la sua soluzione) nel corpo della risposta.

Quali altre condizioni di errore specifiche avevi in ​​mente?

Un'ottima risorsa per scegliere il codice di errore HTTP corretto per la tua API: http://www.codetinkerer.com/2015/12/04/choosing-an-http-status-code.html

Un estratto dall'articolo:

Dove iniziare:

2XX / 3XX:

4XX:

5XX:

La scelta principale è se vuoi trattare il codice di stato HTTP come parte dell'API REST o no.

Entrambi i modi funzionano bene. Concordo sul fatto che, in senso stretto, una delle idee di REST è che è necessario utilizzare il codice di stato HTTP come parte dell'API (restituire 200 o 201 per un'operazione riuscita e un 4xx o 5xx a seconda dei vari casi di errore). Tuttavia , non ci sono polizia REST. Puoi fare quello che vuoi. Ho visto API molto più eclatanti non REST essere chiamate "RESTful".

A questo punto (agosto 2015) ti consiglio di utilizzare il codice di stato HTTP come parte dell'API. Ora è molto più facile vedere il codice di ritorno quando si usano i framework di quanto non fosse in passato. In particolare, ora è più facile vedere il caso di ritorno non 200 e il corpo di risposte non 200 rispetto al passato.

Il codice di stato HTTP fa parte di api

1. Dovrai scegliere attentamente i codici 4xx che si adattano alle tue condizioni di errore. Puoi includere un messaggio di riposo, xml o in chiaro come payload che include un sottocodice e un commento descrittivo.

2. I client dovranno utilizzare un framework software che consenta loro di accedere al codice di stato a livello HTTP. Di solito fattibile, non sempre diretto.

3. I client dovranno distinguere tra i codici di stato HTTP che indicano un errore di comunicazione e i propri codici di stato che indicano un problema a livello di applicazione.

Il codice di stato HTTP NON fa parte dell'API

1. Il codice di stato HTTP sarà sempre 200 se l'app ha ricevuto la richiesta e quindi ha risposto (casi di successo e di errore)

2. TUTTE le tue risposte dovrebbero includere informazioni "busta" o "intestazione". In genere qualcosa come:

   envelope_ver: 1.0
   status: # usa tutti i codici che ti piacciono. Prenota un codice per il successo.
   msg: "ok" # Una stringa umana che riflette il codice. Utile per il debug.
   data: ... # I dati della risposta, se presenti.

3. Questo metodo può essere più semplice per i client poiché lo stato della risposta è sempre nello stesso posto (non sono necessari sottocodici), nessun limite sui codici, non è necessario recuperare il codice di stato a livello HTTP.

Ecco un post con un'idea simile: http://yuiblog.com/blog/2008/10/15/datatable-260-part-one/

Problemi principali:

1. Assicurati di includere i numeri di versione in modo da poter successivamente modificare la semantica dell'API, se necessario.

2. Documento...

Ricorda che ci sono più codici di stato di quelli definiti nelle RFC HTTP / 1.1, il registro IANA è su http://www.iana.org/assignments/http-status-codes . Nel caso in cui hai menzionato il codice di stato 507 suona bene.

Come altri hanno sottolineato, avere un'entità di risposta in un codice di errore è perfettamente consentito.

Ricorda che gli errori 5xx sono sul lato server, ovvero il client non può modificare nulla nella sua richiesta per far passare la richiesta. Se la quota del client viene superata, questo non è sicuramente un errore del server, quindi 5xx dovrebbe essere evitato.

Esistono due tipi di errori. Errori dell'applicazione ed errori HTTP. Gli errori HTTP servono solo a far sapere al gestore AJAX che le cose sono andate bene e non dovrebbero essere usate per nient'altro.

5xx Errore del server

500 Internal Server Error
501 Not Implemented
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
505 HTTP Version Not Supported
506 Variant Also Negotiates (RFC 2295 )
507 Insufficient Storage (WebDAV) (RFC 4918 )
509 Bandwidth Limit Exceeded (Apache bw/limited extension)
510 Not Extended (RFC 2774 )

2xx successo

200 OK
201 Created
202 Accepted
203 Non-Authoritative Information (since HTTP/1.1)
204 No Content
205 Reset Content
206 Partial Content
207 Multi-Status (WebDAV)

Tuttavia, come progettare gli errori dell'applicazione dipende davvero da te. Stack Overflow per esempio invia un oggetto con response, datae messagele proprietà. Credo che la risposta contenga trueo falseper indicare se l'operazione è andata a buon fine (di solito per le operazioni di scrittura). I dati contengono il payload (in genere per le operazioni di lettura) e il messaggio contiene eventuali metadati aggiuntivi o messaggi utili (come i messaggi di errore quando lo responsesono false).

So che è molto tardi per la festa, ma ora, nel 2013, abbiamo alcuni tipi di media per coprire la gestione degli errori in un modo distribuito (RESTful) comune. Vedere "vnd.error", application / vnd.error + json ( https://github.com/blongden/vnd.error ) e "Dettagli del problema per le API HTTP", application / problem + json ( https: // tools. ietf.org/html/draft-nottingham-http-problem-05 ).

Concordato. La filosofia di base di REST è quella di utilizzare l'infrastruttura web. I codici di stato HTTP sono il framework di messaggistica che consente alle parti di comunicare tra loro senza aumentare il payload HTTP. Sono già stati stabiliti codici universali che trasmettono lo stato della risposta e, pertanto, per essere veramente RESTful, le applicazioni devono utilizzare questo framework per comunicare lo stato della risposta.

L'invio di una risposta di errore in una busta HTTP 200 è fuorviante e impone al client (consumatore API) di analizzare il messaggio, molto probabilmente in modo non standard o proprietario. Anche questo non è efficiente: costringerai i tuoi clienti ad analizzare il payload HTTP ogni volta per capire lo stato di risposta "reale". Ciò aumenta l'elaborazione, aumenta la latenza e crea un ambiente in cui il client può commettere errori.

Modellare la tua API sulle "migliori pratiche" esistenti potrebbe essere la strada da percorrere. Ad esempio, ecco come Twitter gestisce i codici di errore https://developer.twitter.com/en/docs/basics/response-codes

Attenersi alla semantica del protocollo. Utilizzare 2xx per risposte di successo e 4xx, 5xx per risposte di errore, siano esse eccezioni aziendali o altro. Se l'utilizzo di 2xx per qualsiasi risposta fosse stato il caso d'uso previsto nel protocollo, in primo luogo non avrebbero avuto altri codici di stato.

Non dimenticare anche gli errori 5xx per errori dell'applicazione.

In questo caso, che dire di 409 (conflitto)? Ciò presuppone che l'utente possa risolvere il problema eliminando le risorse memorizzate.

In caso contrario, potrebbe funzionare anche 507 (non del tutto standard). Non userei 200 se non usassi 200 per errori in generale.

Se viene superata la quota client, si tratta di un errore del server, evitare 5xx in questa istanza.