Un'API HTTP dovrebbe sempre restituire un corpo?

Riguardo PUT, ma si applica anche al POST. La specifica HTTP sezione 9 è un po 'vuota su regole o addirittura consigli (DOVREBBE) quando arriva allo scenario che stai descrivendo. La riga relativa alla tua domanda è trattata più da vicino:

If a new resource is created, the origin server MUST inform the user agent via the 201 (Created) response. If an existing resource is modified, either the 200 (OK) or 204 (No Content) response codes SHOULD be sent to indicate successful completion of the request.

Non penso che perderò il sonno, ma ti chiederei, cosa guadagni aggiungendo il pezzo di JSON nella risposta? Hai appena prelevato il bulking (OK, ammassato potrebbe essere eccessivo!) La risposta ripetendo in modo meno accurato ciò che il codice di stato dovrebbe già averti detto. Se il tuo PUT ha dato come risultato un nuovo oggetto return 201 (come è l'intenzione di PUT), se ha aggiornato un oggetto return 204.

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

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

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

C'è uno standard API JSON aperto che specifica:

• Un oggetto JSON DEVE essere alla radice di ogni documento 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 completo e hanno sempre alcuni metadati in modo da avere un'idea migliore di come è il server gestire i tuoi dati. L'oggetto di risposta standard indica lo stato dell'indice, se la richiesta ha generato 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 è: quanti controlli degli errori vuoi forzare sui tuoi utenti API? Se ottieni un formato standard per tutte le risposte che viene esteso solo in base al tipo di richiesta, soddisfi la necessità di un documento di reso e puoi facilitare il debugging più facile dai tuoi utenti API.

No per esempio, per 204 risposte non dobbiamo includere il corpo del messaggio. {successo | stato | isuccesso: vero} è ridondante.

In pratica (o dovrei dire nella versione successiva di jquery), la risposta vuota per il tipo di contenuto applicazione / json genera un errore. In un certo senso capisco l'argomento che, poiché è un'applicazione / json, deve avere un corpo json valido. Quindi, 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 restituisce l'applicazione / json per le risposte vuote. Usa semplicemente text / plain o qualcosa e assicurati che il client sia in grado di gestire quel tipo.

Nota Posso solo ricordare 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 caduta MSIE per 204 risposte, quindi non ci sono intestazioni e del contenuto, il che è male. Poiché molti usano MSIE, abbiamo dovuto cambiarlo in 200 status.

No, ma aiuterà la coerenza del tuo codice. È anche utile per scopi di debug. Sarà anche di grande aiuto nella manutenzione del sito web. Ricorda questo: il codice di errore è per macchina, il messaggio di errore è per umano. Quindi ti sto suggerendo di usare un corpo di risposta. In ogni caso, il suo effetto negativo è solo minimo (solo pochi byte inviati sulla rete) rispetto ai suoi benefici. Un'altra cosa, ti eviterà anche di dimenticare di scrivere un messaggio quando è necessario.

Non restituirei semplicemente uno stato di successo nella risposta, il codice di errore http segnala solo il successo o l'errore. Includerei solo la 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 che la richiesta è stata applicata, 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 composta da un oggetto json vuoto , ovvero {} . In questo modo il client ottiene una risposta valida e l'aggiunta di alcune informazioni in un secondo momento è improbabile che 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 di come deve essere utilizzata l'API, è possibile includere una copia dell'oggetto, come esistente dopo il salvataggio.

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

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

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

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

Per essere precisi, in un laboratorio è perfettamente in grado di gestire tutto con i soli 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 stai provando a dire.

Restituzione di 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, (mi dispiace per la struttura delle risposte dei pozzi), fornendo a un pubblico JSON API si rinuncia a un sacco di controllo su come verrà utilizzato. Alcuni client potrebbero reagire in modo diverso a diversi enti (o mancano di) o codici di stato.