Un'API HTTP deve sempre restituire un corpo?

Esiste una sorta di standard per quanto riguarda le risposte API HTTP?

Dopo aver letto questo thread del discorso ho iniziato a chiedermi. Stiamo sviluppando la nostra API JSON HTTP pubblica sul mio lavoro e non restituiamo nulla quando non è strettamente necessario (ad esempio un PUT in / resource / {id} restituisce 200 solo quando OK o il corrispondente codice 4XX o 5XX, ma no Corpo JSON)

Dovremmo restituire un generico {"success":true}come discusso su quel link sopra, o è giusto restituire un corpo "vuoto" e gestire tutto con i codici di risposta http?

Per quanto riguarda PUT, ma vale anche per POST. La sezione 9 delle specifiche HTTP è un po 'vuota sulle regole o anche sui consigli (DOVREBBE) quando si tratta dello scenario che stai descrivendo. La linea pertinente alla tua domanda è più strettamente coperta da:

Se viene creata una nuova risorsa, il server di origine DEVE informare l'agente utente tramite la risposta 201 (creata). Se una risorsa esistente viene modificata, i codici di risposta 200 (OK) o 204 (Nessun contenuto) DOVREBBERO essere inviati per indicare il completamento con successo della richiesta.

Non penso che ci perderei il sonno, ma vorrei chiedere, cosa guadagni aggiungendo il pezzo di JSON nella risposta? Hai appena eliminato (OK, il bulked potrebbe essere eccessivo!) La risposta ripetendo in modo meno accurato ciò che il codice di stato avrebbe già dovuto dirti. Se il tuo PUT ha comportato un nuovo oggetto restituisce 201 (come lo è l'intenzione di PUT), se ha aggiornato un oggetto restituisce 204.

Per inciso, API a parte, invece di 200, se non restituisci nulla usa 204.

Supponendo che stai sviluppando una serie di interfacce RESTful, non esiste uno standard in sé, quindi qualunque cosa tu faccia, documentalo bene, fornisci esempi e tutto andrà bene.

Lo standard HTTP di base non impone che ci sia un documento restituito con una risposta. Per motivi di economia, quando uno stato HTTP trasmette tutto ciò che è richiesto, il corpo sarebbe sprecato. Tuttavia, ci sono standard basati su HTTP che aggiungono nuove regole.

Esiste uno standard API JSON aperto che specifica:

• Un oggetto JSON DEVE trovarsi alla radice di ogni documento di risposta dell'API JSON . (il corsivo rappresenta ciò che ho aggiunto per chiarire il testo)

Sfortunatamente, lo standard non specifica come rappresentare un documento vuoto ed è un work in progress. Nel migliore dei casi lo userei come linea guida.

Alcune applicazioni (come ElasticSearch ) forniscono un'API JSON completa e dispongono sempre di alcuni metadati in modo da poter avere un'idea migliore di come il server gestisce i dati. L'oggetto risposta standard indica lo stato dell'indice, se la richiesta ha provocato un errore, quanti nodi sono stati interessati, ecc. ElasticSearch utilizza "application / json" per il tipo mime, quindi è improbabile che stiano applicando le linee guida in lo standard jsonapi.org.

JQuery e framework JavaScript simili presuppongono che ci sarà sempre un documento. La domanda è: quanto controllo degli errori vuoi imporre ai tuoi consumatori API? Se si ottiene un formato standard per tutte le risposte che viene esteso solo in base al tipo di richiesta, si soddisfa la necessità di un documento di ritorno e si può facilitare il debug più semplice da parte dei consumatori API.

No, ad esempio, per 204 risposte non dobbiamo includere il corpo del messaggio. {success | status | isSuccessful: true} è ridondante.

In pratica (o dovrei dire nella versione successiva di jquery), la risposta vuota per il tipo di contenuto application / json genera errore. Capisco l'argomento secondo cui poiché è application / json deve avere un corpo json valido. Pertanto, la risposta vuota per il tipo di contenuto application / json sarebbe 'null' o '{}' che sono json validi.

C'è un altro modo che dovrebbe funzionare per jquery, che non sta restituendo application / json per risposte vuote. Usa semplicemente text / plain o qualcosa del genere e assicurati che il client sia in grado di gestire quel tipo.

Nota Ricordo solo 204 per il divieto esplicito di restituire il corpo del messaggio. Quello che abbiamo scoperto è che non possiamo sempre usare 204. Il problema è l'intestazione della risposta di rilascio MSIE per 204 risposte, quindi non ci sono contenuti e intestazioni, il che è male. Dato che molti usano MSIE, abbiamo dovuto cambiarlo a 200 status.

No, ma contribuirà alla coerenza del codice. Buono anche per scopi di debug. Sarà anche di grande aiuto nella manutenzione del sito web. Ricorda questo: il codice di errore è per la macchina, il messaggio di errore è per l'uomo. Quindi ti sto suggerendo di usare un corpo di risposta. Comunque, il suo effetto negativo è solo minimo (solo pochi byte inviati sulla rete) rispetto ai suoi vantaggi. Un'altra cosa, ti eviterà anche di dimenticare di scrivere un corpo del messaggio quando è necessario.

Non restituirei semplicemente uno stato di successo nella risposta, il codice di errore http segnala solo successo o errore. Includerei solo l'uso della risposta stessa per aggiungere informazioni dettagliate sull'errore come codici di errore specifici dell'applicazione o messaggi di errore.

Per le richieste PUT, PATCH e POST in genere si restituisce lo stato restituisce lo stato della risorsa dopo l'applicazione della richiesta, non una risposta vuota.

Per le richieste POST che rappresentano un'azione invece di creare semplicemente una risorsa (non molto RESTful, ma comunque utile nella pratica), che non ha dati utili da restituire, restituirei una risposta consistente in un oggetto json vuoto, vale a dire {}. In questo modo il client ottiene una risposta valida e è improbabile che l'aggiunta di alcune informazioni in seguito la rompa.

Per le richieste DELETE che restituiscono 204 e un corpo vuoto è piuttosto comune, il che ha senso poiché la risorsa non esiste in seguito.

Suggerirei di restituire solo ciò che è necessario + un piccolo chiarimento.

Ad esempio, a seconda dell'utilizzo dell'API, è possibile includere una copia dell'oggetto, così come esiste dopo il salvataggio.

Quindi un POST di {chiave: 123} potrebbe restituire {chiave: 123, pippo: 'bar'}.

L'idea di base è che è meglio restituire l'oggetto e doverlo interrogare nuovamente.

Detto questo, i tuoi consumatori API non hanno bisogno dell'oggetto non è necessario restituirlo.

Di solito restituisco {success: true} o qualcosa del genere, quando non ci sono oggetti richiesti su POST PUT e PATCH perché facilita la ricezione. Detto questo, è meglio che il 99% delle volte restituisca la rappresentazione salvata dell'oggetto, è raro che non ne abbiano bisogno comunque, ed è "più economico" inviarlo tutto in una richiesta e poi in due.

Per essere precisi, in un laboratorio si trova perfettamente a gestire tutto con solo codici di stato, nel mondo reale, è molto meglio restituire alcuni dati, anche se ridondanti, in modo che i consumatori di API possano facilmente capire cosa stanno cercando di dire.

Restituire 200 {success: true} consente alle persone di scrivere codice in entrambi i modi:

if response.code == 200
  do stuff
end

e

if response.body.success
  do stuff
end

inoltre non è così difficile da parte tua.

Infine, (scusate per la struttura di risposta di poos), fornendo a un api JSON pubblico il vostro abbandono di un sacco di controllo su come verrà utilizzato. Alcuni client possono reagire in modo diverso a diversi organismi (o mancare di essi) o codici di stato.