Sto lavorando a un progetto e dopo aver litigato con le persone al lavoro per circa un'ora. Ho deciso di sapere cosa avrebbero potuto dire le persone in borsa.

Stiamo scrivendo un'API per un sistema, c'è una query che dovrebbe restituire un albero dell'organizzazione o un albero degli obiettivi.

L'albero dell'organizzazione è l'organizzazione in cui l'utente è presente, in altre parole, questo albero dovrebbe sempre esistere. Nell'organizzazione, dovrebbe essere sempre presente un albero degli obiettivi. (è qui che è iniziata la discussione). Nel caso in cui l'albero non esista, il mio collega ha deciso che sarebbe stato giusto rispondere alla risposta con il codice di stato 200. E poi ha iniziato a chiedermi di correggere il mio codice perché l'applicazione stava andando in pezzi quando non c'era albero.

Proverò a risparmiare fiamme e furia.

Ho suggerito di generare un errore 404 quando non è presente alcun albero. Almeno mi farebbe sapere che qualcosa non va. Quando uso 200, devo aggiungere un controllo speciale alla mia risposta nel callback di successo per gestire gli errori. Mi aspetto di ricevere un oggetto, ma potrei effettivamente ricevere una risposta vuota perché non viene trovato nulla. Sembra del tutto corretto contrassegnare la risposta come 404. E poi è iniziata la guerra e ho ricevuto il messaggio che non capivo lo schema del codice di stato HTTP. Quindi sono qui e chiedo cosa c'è che non va in 404 in questo caso? Ho anche avuto l'argomento "Non ha trovato nulla, quindi è giusto restituire 200". Credo che sia sbagliato poiché l'albero dovrebbe essere sempre presente. Se non abbiamo trovato nulla e ci aspettiamo qualcosa, dovrebbe essere un 404.

Ulteriori informazioni,

Ho dimenticato di aggiungere gli URL recuperati.

organizzazioni

/OrgTree/Get

obiettivi

/GoalTree/GetByDate?versionDate=...
/GoalTree/GetById?versionId=...

Errore mio, sono richiesti entrambi i parametri. Se viene fornita una versione di Date che può essere analizzata in una data, verrà restituita la revisione di chiusura. Se inserisci qualcosa in passato, verrà restituita la prima revisione. Se per ID con un ID che non esiste, sospetto che restituirà una risposta vuota con 200.

Extra

Inoltre, credo che la migliore risposta al problema sia creare oggetti predefiniti quando vengono create le organizzazioni, non avere un albero non dovrebbe essere un caso valido e dovrebbe essere visto come un comportamento indefinito. Non è possibile utilizzare un account senza entrambi gli alberi. Per questo motivo, dovrebbero essere sempre presenti.

anche questo mi è stato collegato (uno simile ma non riesco a trovarlo)

http://viswaug.files.wordpress.com/2008/11/http-headers-status1.png

In caso di dubbi, consultare la documentazione . La revisione delle definizioni del W3C per i codici di stato HTTP ci fornisce questo:

200 OK - La richiesta è riuscita. Le informazioni restituite con la risposta dipendono dal metodo utilizzato nella richiesta.

404 non trovato: il server non ha trovato nulla corrispondente all'URI di richiesta.

Nel contesto dell'API, dipende molto da come vengono create le query e da come vengono recuperati gli oggetti. Ma la mia interpretazione è sempre stata quella:

• Se chiedo un oggetto particolare ed esiste un 200codice di ritorno , se non esiste restituisci il 404codice corretto .
• Ma, se chiedo un set di oggetti che corrispondono a una query, un set null è una risposta valida e voglio che venga restituito con un 200codice. La logica di ciò è che la query era valida, è riuscita e la query non ha restituito nulla.

Quindi in questo caso hai ragione , il servizio non sta cercando "una cosa specifica", ma sta richiedendo una cosa particolare, se quella cosa non viene trovata, dillo chiaramente.

Penso che Wikipedia lo metta meglio:

200 OK - ... La risposta effettiva dipenderà dal metodo di richiesta utilizzato. In una richiesta GET, la risposta conterrà un'entità corrispondente alla risorsa richiesta.

404 non trovato: la risorsa richiesta non è stata trovata ma potrebbe essere nuovamente disponibile in futuro. Sono consentite richieste successive da parte del cliente.

Mi sembra piuttosto chiaro.

Per quanto riguarda le richieste di esempio

/GoalTree/GetByDate?versionDate=...
/GoalTree/GetById?versionId=...

Per il formato, hai detto, restituisci sempre la revisione più vicina a quella data. Non restituirà mai un oggetto, quindi dovrebbe sempre tornare 200 OK. Anche se questo fosse in grado di prendere un intervallo di date e la logica dovesse restituire tutti gli oggetti entro quel lasso di tempo restituendo 200 OK - 0 I risultati sono ok, poiché questo è ciò che la richiesta era - l'insieme di cose che soddisfacevano quei criteri.

Tuttavia, quest'ultimo è diverso in quanto si richiede un oggetto specifico , presumibilmente unico, con quell'identità. La restituzione 200 OKin questo caso è errata poiché la risorsa richiesta non esiste e non viene trovata .

Per quanto riguarda la scelta dei codici di stato

• Codici 2xx Dì ad un UA che ha fatto la cosa giusta , la richiesta ha funzionato. Può continuare a farlo in futuro.
• Codici 3xx Racconta a un UA quello che probabilmente hai chiesto di lavorare, ma quella cosa è ora altrove. In futuro l'UA potrebbe prendere in considerazione l'idea di andare al reindirizzamento .
• Codici 4xx Indica a UA che ha fatto qualcosa di sbagliato , la richiesta che ha costruito non è corretta e non dovrebbe riprovare, senza almeno qualche modifica.
• Codici 5xx Dire a un UA che il server è in qualche modo rotto . Ma hey quella query potrebbe funzionare in futuro, quindi non c'è motivo di non riprovare. (ad eccezione di 501, che è più di un problema di 400).

Hai menzionato in un commento usando un codice 5xx, ma il tuo sistema funziona. È stata chiesta una query che non funziona e deve comunicarla agli Emirati Arabi Uniti. Non importa come lo tagli, questo è il territorio 4xx.

Considera un alieno che interroga il nostro sistema solare

Alieno: computer, per favore, dimmi tutti i pianeti in cui abitano gli umani.

Computer: 1 risultato trovato. Terra

Alieno: computer, per favore, parlami della Terra .

Computer: Terra - Per lo più innocuo.

Alieno: computer, per favore, parlami di tutti i pianeti in cui vivono gli umani, al di fuori della fascia degli asteroidi.

Computer: 0 risultati trovati.

Alieno: computer, per favore, distruggi la Terra.

Computer: 200 OK.

Alieno: computer, per favore, parlami della Terra .

Computer: 404 - Non trovato

Alieno: computer, per favore, dimmi tutti i pianeti in cui abitano gli umani.

Computer: 0 risultati trovati.

Alien: vittoria del potente impero Irken!

Ignorando il fatto che / GoalTree / Get * assomiglia a un verbo, non a risorse, dovresti sempre restituire 200 perché l'URI / GoalTree / Get * rappresentano risorse che sono sempre disponibili per l'accesso e non è un errore client se non ci sono alberi come risultato di una richiesta. Restituisci solo 200 con set vuoto quando non è necessario restituire alcuna entità.

Si utilizza 404 se la risorsa non viene trovata, non quando non è presente alcuna entità.

Mettilo in un altro modo, se vuoi restituire 404 per i tuoi oggetti, quindi dai loro i loro URI.

Questa è una domanda interessante, perché riguarda le specifiche del sistema.

La risposta di imel96 mi ha convinto che un 404 non sarebbe una risposta adeguata, poiché la famiglia di codici 4xx è principalmente per errori utente / client , e questo non è uno. L'URL è ben formato e l'albero deve essere lì; in caso contrario, il sistema si trova in uno stato incoerente!

Pertanto questo è un errore del server , vale a dire qualcosa nella famiglia 5xx. Forse un errore generico del server interno 500 o un servizio 503 non disponibile (il servizio è "prendimi l'albero che deve essere lì").

Direi che un codice di risposta 200 o 404 può essere valido , a seconda di come guardi la situazione.

Il fatto è che i codici di risposta HTTP sono definiti nel contesto di un server , che può fornire varie risorse in base al loro URL. In questo contesto, i significati di 200 OKe 404 Not Foundsono perfettamente inequivocabili: il primo dice "ecco la risorsa che hai chiesto", mentre il secondo dice "scusa, non ho alcuna risorsa del genere".

Tuttavia, nella tua situazione, hai un ulteriore livello di applicazione tra il server HTTP e le risorse effettive (alberi) che vengono richieste. L'applicazione occupa una sorta di spazio intermedio che non è ben indirizzato nelle specifiche HTTP.

Dal punto di vista del server web, l'applicazione sembra un po ' come una risorsa: in genere è un file sul server, identificato da (una parte di) l'URL, proprio come altre risorse (ad esempio file statici) che il server potrebbe servire. D'altra parte, è un tipo strano di risorsa, poiché consiste in un codice eseguibile che determina dinamicamente il contenuto, e in effetti potenzialmente anche il codice di stato, della risposta, facendolo comportare in qualche modo più come un mini-server.

In particolare, nel tuo esempio, il server web può individuare correttamente l'applicazione, ma l'applicazione non riesce a individuare l'origine secondaria (albero) che è stata richiesta. Ora, se consideri l'applicazione come un'estensione del server e il subitem (albero) la risorsa effettiva, allora una risposta 404 è appropriata: il server ha semplicemente delegato il compito di trovare la risorsa effettiva all'applicazione , che a sua volta non è riuscito a farlo.

D'altra parte, se il tuo punto di vista è che l'applicazione è la risorsa richiesta, ovviamente il server web dovrebbe restituire una risposta 200 ; dopo tutto, l'applicazione è stata trovata ed eseguita correttamente. Ovviamente, in questo caso, l'applicazione dovrebbe effettivamente restituire un corpo di risposta valido nel formato previsto, indicando (utilizzando qualunque protocollo di livello superiore codificare il formato) che non sono stati trovati dati effettivi corrispondenti alla query.

Entrambi questi punti di vista possono avere senso. Nella maggior parte dei casi , almeno per le applicazioni a cui si accede direttamente tramite HTTP con un normale browser Web, preferirei la prima vista : l'utente in genere non si preoccupa dei dettagli interni come la differenza tra il server e l'applicazione, semplicemente preoccuparsi se i dati desiderati sono presenti o meno.

Tuttavia, nel caso specifico di un'applicazione progettata per comunicare con altri programmi per computer utilizzando un protocollo API di alto livello personalizzato, utilizzando HTTP solo come livello di trasporto di basso livello , c'è un argomento da sostenere a favore di quest'ultima vista : per i client che si interfacciano con tale applicazione, a loro interessa davvero, a livello HTTP , è se sono riusciti a contattare correttamente l'applicazione o meno. Tutto il resto, in questi casi, viene spesso comunicato in modo più naturale utilizzando il protocollo di livello superiore.

In ogni caso, indipendentemente da quale delle viste sopra preferite, ci sono alcuni dettagli da tenere a mente. Uno è che, in molti casi, potrebbe esserci una distinzione significativa tra una risorsa (essenzialmente) vuota e una risorsa inesistente .

A livello HTTP, una risorsa vuota verrebbe semplicemente indicata da un codice di 200 risposte e da un corpo di risposta vuoto, mentre una risorsa inesistente sarebbe indicata da una risposta 404 e da un corpo di risorse che spiega l'assenza della risorsa. In un protocollo API di livello superiore, in genere si indica una risorsa inesistente mediante una risposta di errore, contenente un codice / messaggio di errore specifico del protocollo appropriato, mentre una risposta vuota sarebbe semplicemente una normale struttura di risposta senza elementi di dati.

(Si noti che una risorsa non deve essere letteralmente a zero byte per essere "vuota" nel senso che intendo sopra. Ad esempio, un risultato di ricerca senza elementi corrispondenti viene considerato vuoto in senso lato, come un risultato di una query SQL con nessuna riga o un documento XML che non contiene dati reali.)

Inoltre, naturalmente, se l'applicazione davvero crede che la subresource richiesto dovrebbe essere lì, ma non riesce a trovarlo, allora esiste un terzo codice di risposta possibile: 500 Internal Server Error. Tale risposta ha senso se l'esistenza della risorsa è una condizione preliminare per l'applicazione, tale che la sua assenza indica necessariamente un malfunzionamento interno.

Infine, dovresti sempre tenere presente la legge di Postel :

" Sii prudente in ciò che invii e liberale in ciò che ricevi. "

Se il server deve rispondere in una situazione particolare con un 200 o una risposta 404, che non scusa si come il cliente implementor dalla manipolazione sia la risposta in modo appropriato e con le modalità che massimizza l'interoperabilità robusto. Naturalmente, si può sostenere cosa significhi una manipolazione "appropriata" in diverse situazioni, ma di solito non dovrebbe includere crash o "caduta".

Che ne dici di un 204 Nessun contenuto? Suggerirebbe che la tua richiesta sia stata elaborata correttamente ma non restituisca nulla. È ancora un "successo" ma ti consente di vedere se hai risultati basati solo sul codice di stato.

Se l'URL rappresenta una risorsa che non è mai esistita, restituire 404 Not Found

Se l'URL rappresenta una risorsa che è un elenco vuoto, restituire un elenco vuoto e 200 OK.

Esempio:

{
  total: 0,
  items: []
}

Se l'URL rappresenta una risorsa che esisteva in precedenza, restituire 410 Andato.

Per quanto riguarda il dialogo di Lego Stormtrooper:

Alien: Computer, please tell me all planets that humans inhabit. GET /planets?inhabitedBy=humans

Computer: 200 OK. { total: 1, items:[{name:'Earth'}] }

Alien: Computer, please tell me about Earth. GET /planets/earth

Computer: 200 OK. {name:'Earth', status: 'Mostly Harmless'}

Alien: Computer, please tell me about all planets humans inhabit, outside the asteroid belt. GET /planets?inhabitedBy=humans&distanceFromSun=lots

Computer: 200 OK. {total:0, items:[] }

Alien: Computer, please destroy Earth. DELETE /planets/earth

Computer: 204 No Content. (or 202 Accepted if it takes some time to destroy Earth)

Alien: Computer, please tell me about Earth. GET /planets/earth

Computer: 410 Gone

Alien: Computer, please tell me all planets that humans inhabit. GET /planets?inhabitedBy=humans

Computer: 200 OK 0 {total: 0, items:[] }

Alien: Victory for the mighty Irken Empire!

A quanto pare, questa è un'API per uso interno . Ciò offre il vantaggio di utilizzare qualsiasi schema che offra il massimo beneficio , indipendentemente dal fatto che sia o meno una specifica (specifica). Questo non significa inventare completamente i tuoi codici di stato, ma è OK "piegare" un po 'le regole se è utile.

Concordo con la tua posizione sul fatto che dovresti ottenere un codice di stato che mostri che qualcosa è andato storto. Dopo tutto, questo è ciò a cui servono i codici di stato. Inoltre ottieni il vantaggio di librerie che generano eccezioni / ecc. su un codice di stato diverso da 200, quindi non è necessario controllare esplicitamente (oppure è possibile scrivere il proprio wrapper che lo fa).

Concordo anche con il punto di vista di Andres F. che 500 è appropriato poiché l'albero dovrebbe esistere. In pratica, però, mi piace dividere gli errori del server in due categorie. Qualcosa di inaspettato è andato storto e qualcosa che posso praticamente verificare è andato storto. Ciò comporta i seguenti codici di stato,

• 200 - Va tutto bene
• 404 - URL errato
• 409 - Qualcosa è andato storto
• 500 - Si è verificato un errore imprevisto sul server

Nel tuo caso particolare, puoi verificare se l'albero esiste o meno sul lato server e se non è presente restituisce un 409. È un errore previsto (sai che può succedere, puoi verificarlo, ecc.) . Il conflitto 409 è solo la mia preferenza personale, un 5xx può anche essere appropriato fintanto che puoi sederti e decidere questo con la tua squadra.

La categorizzazione di codici come questo consente di identificare più rapidamente il tipo di errore, ma può avere vantaggi oltre l'organizzazione. Spesso con errori del sito Web non si desidera che il client riceva errori imprevisti in quanto ciò può essere un problema di sicurezza e rivelare vulnerabilità in modo da restituire un 500 generico "Si è verificato un errore". e registra l'errore completo sul server. Ma se si verifica un errore previsto come 409, sai che sarebbe sicuro mostrare l'errore al client e non devi lasciarli nell'oscurità di ciò che è successo. Questo è solo un uso pratico che posso raccontare, ma ci sono molte possibilità.

Questo è un po 'un problema, perché lo stai postando perché non sei in grado di essere d'accordo con i tuoi colleghi, ma sembra che voi ragazzi stiate discutendo di più sulla semantica e chi sia politicamente corretto. Non importa davvero chi è più adatto, a patto che tu possa trovare un sistema che avvantaggia maggiormente l'azienda.

D'altra parte, se si tratta di un'API pubblica che segue le specifiche il più vicino possibile, sarebbe più importante evitare la confusione nella comunità.

Dare una spinta tangenziale a questo: se un essere umano alla fine sta usando l'API (tramite una GUI), suggerirei di fare qualunque cosa renda la vita facile per l'utente finale. La non esistenza dell'albero quando dovrebbe esistere è un errore "Incoerenza del modello di dominio". Un errore di sistema è quando hai esaurito la memoria o hai avuto qualche altro errore sistemico. Quindi restituire 5xx è inappropriato. Come menzionato da molte persone sopra, 4xx potrebbe essere appropriato se l'albero stesso avesse il suo URI, che non è il caso qui. Ma ecco cosa dice 404 al cliente: puoi riprovare ancora e ancora finché non ricevi qualcosa in cambio. Se hai restituito 200, potresti restituire una diagnostica sufficiente all'utente o all'agente utente in modo che l'agente utente possa visualizzare un messaggio in modo che l'utente smetta di riprovare e contatta solo l'assistenza. D'altra parte se questa API è destinata solo ai sistemi,