web-services - framework - creare api




L'errore dell'API REST restituisce buone pratiche (8)

Sto cercando indicazioni su buone pratiche quando si tratta di restituire errori da un'API REST. Sto lavorando su 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.

Aggiungo ora alcuni casi di errore, 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 i codici di stato HTTP (401 per l'autenticazione, 403 per l'autorizzazione e 404 per gli URI con richiesta non valida). Ho esaminato i beati codici di errore HTTP ma nessuno degli intervalli 400-417 sembra corretto riportare errori specifici dell'applicazione. Quindi all'inizio sono stato tentato di restituire il mio errore di applicazione con 200 OK e uno specifico payload XML (ad esempio, pagaci di più e avrai lo spazio di cui hai bisogno!) Ma mi sono fermato a pensarci e sembra insaponato (/ scrollando le spalle nell'orrore). Inoltre sembra che io stia dividendo le risposte di errore in casi distinti, in quanto alcuni sono guidati dal codice di stato http e altri sono guidati dal contenuto.

Quindi, quali sono le raccomandazioni del settore? Buone pratiche (spiegate perché!) E anche, da un cliente pov, che tipo di gestione degli errori nell'API REST rende la vita più facile per il codice client?


Quindi all'inizio sono stato tentato di restituire il mio errore di applicazione con 200 OK e uno specifico payload XML (ad esempio, pagaci di più e avrai lo spazio di cui hai bisogno!) Ma mi sono fermato a pensarci e sembra insaponato (/ scrollando le spalle nell'orrore).

Non vorrei restituire 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 DEVE essere ripetuta. Se il metodo di richiesta non era HEAD e il server desidera rendere pubblico perché la richiesta non è stata soddisfatta, DOVREBBE descrivere il motivo del rifiuto nell'entità. Se il server non desidera rendere queste informazioni disponibili al client, è possibile utilizzare il codice di stato 404 (non trovato).

Questo dice al cliente che la richiesta era OK, ma che non ha funzionato (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?


Ci sono due tipi di errori. Errori di applicazione e HTTP. Gli errori HTTP servono solo a far sapere al tuo 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, il modo in cui progetta gli errori dell'applicazione dipende solo da te. , ad esempio, invia un oggetto con proprietà di response , data e message . La risposta che ritengo contiene true o false per indicare se l'operazione ha avuto esito positivo (in genere per le operazioni di scrittura). I dati contengono il carico utile (in genere per le operazioni di lettura) e il messaggio contiene ulteriori metadati o messaggi utili (come i messaggi di errore quando la response è false ).


Concordato. La filosofia di base di REST è 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 dei codici universali che comunicano 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 costringe il cliente (api consumer) ad analizzare il messaggio, molto probabilmente in modo non standard o proprietario. Anche questo non è efficiente: costringerai i tuoi clienti a analizzare il payload HTTP ogni volta per capire lo stato di risposta "reale". Ciò aumenta l'elaborazione, aggiunge latenza e crea un ambiente in cui il cliente può commettere errori.


La scelta principale è se desideri trattare il codice di stato HTTP come parte della tua API REST o no.

Entrambe le strade funzionano bene. Sono d'accordo sul fatto che, in senso stretto, una delle idee di REST è che dovresti usare il codice di stato HTTP come parte della tua API (restituire 200 o 201 per un'operazione riuscita e un 4xx o 5xx a seconda dei vari casi di errore). , non ci sono poliziotti REST. Puoi fare quello che vuoi. Ho visto molte più importanti API non REST chiamate "RESTful".

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

Il codice di stato HTTP fa parte della tua API

  1. Dovrai selezionare attentamente i codici 4xx adatti alle tue condizioni di errore. È possibile includere un messaggio di resto, xml o testo in chiaro come carico utile che include un sottocodice e un commento descrittivo.

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

  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 della tua API

  1. Il codice di stato HTTP sarà sempre 200 se la tua app ha ricevuto la richiesta e poi ha risposto (sia casi di successo che di errore)

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

    envelope_ver: 1.0
    status:  # use any codes you like. Reserve a code for success. 
    msg: "ok" # A human string that reflects the code. Useful for debugging.
    data: ...  # The data of the response, if any.
  3. Questo metodo può essere più semplice per i client poiché lo stato per la risposta è sempre nello stesso posto (non sono necessari sottocodici), nessun limite sui codici, nessuna necessità di 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 modificare la semantica dell'API in seguito, se necessario.

  2. Documento...


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

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

Altrimenti potrebbe funzionare anche il 507 (non del tutto standard). Non userei 200 se non si usa 200 per errori in generale.



Si prega di attenersi alla semantica del protocollo. Utilizza 2xx per le risposte corrette e 4xx, 5xx per le risposte di errore, che si tratti delle eccezioni aziendali o di altro tipo. Avendo usato 2xx per qualsiasi risposta era il caso d'uso previsto nel protocollo, non avrebbero in primo luogo altri codici di stato.








rest