L'API RESTful rappresenta l'assenza di qualcosa

Immagina un'API per identificare se una persona ha selezionato il suo animale spirituale. Possono avere solo zero o un animale spirito.

Attualmente:

/person/{id}/selectedSpiritAnimal

quando hanno selezionato un animale restituisce http 200 e {selectedAnimal:mole}

ma quando non hanno alcuna selezione, restituisce http 404.

Questo rende il mio animale spirituale infelice poiché rappresentiamo una preoccupazione di dominio valida - non avendo ancora selezionato un animale spirituale - come un errore HTTP.

Inoltre, come azienda - erm Sprit-Animal-Hampers-R-us - vogliamo sapere quando qualcuno non ha alcuna selezione in modo da poterlo sollecitare.

Qual è una risposta migliore qui:

HTTP 200 e {selectedAnimal:null}

o ancora più esplicito

HTTP 200 e {selectedAnimal:null, spiritAnimalSelected: false}

O è meglio restituire un 404? Dal momento che molto simile this image has not yet been uploadedalla visualizzazione di un'immagine online sarebbe un 404. this person has not selected a spirit animalpotrebbe essere un 404

Questa domanda è stata proposta come duplicata, ma quella domanda affronta un URL altrimenti valido richiesto quando l'applicazione è stata configurata per non consentire la modifica rappresentata dall'URL.

Mentre qui sto osservando come si rappresenta una risorsa in cui l'assenza della risorsa è significativa. Vale a dire che è valido per il client richiedere l'URL e la risposta è che hai richiesto correttamente la risorsa che rappresenta un'assenza di una cosa.

Quindi questa non è una "logica di business", ma piuttosto una circostanza in cui l'assenza di qualcosa ha un significato (potrebbe essere come molti dei miei colleghi sostengono che 404 sia ancora corretto) ma non sono sicuro di come mapparlo al spec.

Molto difficile scegliere una risposta. Ho cambiato idea più volte durante la conversazione qui e quella in corso al lavoro.

La cosa che lo risolve per me qui è che la specifica dice che un 4xx è quando il client ha sbagliato . In questo caso al cliente è stato detto di aspettarsi una risposta dall'URL selezionatoSpiritAnimal, quindi non ha commesso errori.

Il consenso tra i miei colleghi è che questo è un sintomo di una cattiva progettazione delle API

Probabilmente sarebbe meglio che semplicemente richiedessimo / person / {id} e che restituisca un insieme di relazioni di link per la persona ... quindi se non ti viene dato il link / selectedSpiritAnimal (quando una persona non ha selezione) ma tu chiamalo comunque allora un 404 ha un senso. Oppure implementare risposte parziali e lasciare che / person / {id} restituisca un documento più completo a meno che il cliente non richieda un sottoinsieme dei dati

I codici HTTP 4xx non sono probabilmente la scelta giusta per questo scenario. Dichiarate che avere zero animali spirituali è uno stato valido e la rotta API spiegherà person/{id}/selectedSpiritAnimalse la persona ne idha o meno uno.

Le risposte HTTP 4xx sono riservate alla situazione in cui un client ha fatto qualcosa di errato nella richiesta (consultare l'archivio di w3 delle specifiche originali ). Ma il cliente sta facendo una richiesta valida, indipendentemente dal fatto che una persona idabbia o meno un animale spirituale.

Quindi mi appoggio alle seconde soluzioni usando un corpo JSON correttamente formattato nella risposta e un codice HTTP 2xx.

Ora se ricevi una tale richiesta e risulta che la persona idnon esiste, un codice 4xx ha più senso.

Lascia che ti presenti il modello di maturità Richardson .

Il tuo problema è che stai rappresentando due risorse come una, dove dovresti davvero avere due risorse che hanno una relazione indicata da hypermedia. Usare l'ipermedia per descrivere le relazioni è il glorioso livello 3 di Riposo.

La tua persona dovrebbe vivere sotto l'URI /person/{id}e l'animale dovrebbe vivere sotto /spiritanimal/{id}. La persona dovrebbe indicare che ha un animale spirituale usando un collegamento all'animale.

Immaginiamo una persona di nome Bob, che ha l'ID 123 e un animale spirito unicorno.

GET /person/123

ritornerebbe;

{
  "name": "Bob",
  "links": [
    {
      "rel": "spiritanimal",
      "uri": "/spiritanimals/789"
    }
  ]
}

Ora chiunque legga la persona 123 saprà di avere un animale spirituale e ha l'URI dove può ottenere maggiori informazioni su di esso.

GET /spitiranimal/789

potrebbe tornare

{
  "type": "Unicorn"
}

Ora immaginiamo una persona di nome Fred, che ha l'id 456 e nessun animale spirituale.

GET /person/456

ritornerebbe;

{
  "name": "Fred",
  "links": [
  ]
}

Ora chiunque leggerà la persona 456 saprà di non avere un animale spirituale, poiché non esiste alcun collegamento. Non è necessario utilizzare alcun codice di stato HTTP per rappresentare la mancanza di una relazione.

Questo è l'URL appropriato per ottenere animali spirituali; pertanto, un errore 404 non è appropriato. 404 è per rappresentare un problema tecnico, non un problema logico.

La soluzione appropriata è restituire http 200 e {"selectedAnimal": null}

Dovresti avere un metodo web separato/person/{id}/hasSelectedSpiritAnimal che ritorna {"isSpiritAnimalSelected": false}. Dietro le quinte, può o meno effettuare le stesse chiamate del metodo, restituendo false se nulle, ma sta a lui decidere, non il codice consumante.

È meglio evitare di combinare query separate in un metodo Web senza un motivo convincente per farlo, anche se le query sono strettamente correlate.

Ciò che rappresenta il tuo endpoint non è solo un animale; è un animale o mancanza di esso. È un valore rappresentato al meglio da un Optional/ Maybe/ Nullable/ ecc.

Quindi i valori legittimi (come in 200 OK) possono essere:

• {'animal': <some animal>, 'selected': true}
• {'animal': null, 'selected': false}

Potevo immaginare che DELETEil metodo, quando applicato al punto finale, può impostare 'selected'a falsevolta, che è, disinserire l'animale selezionato.

Puoi, ovviamente, rilasciare la 'selected'chiave qui, è mostrata solo per chiarezza; stringa vs nullè sufficiente per la distinzione.

Dovresti usare 404.

Il codice di stato 404 (non trovato) indica che il server di origine non ha trovato una rappresentazione corrente per la risorsa di destinazione

RFC7231

HTTP/1.1 200 OK
Content-Type: application/json
Date: Mon, 25 Sep 2017 00:00:00 GMT

"mole"

HTTP/1.1 404 Not Found
Content-Type: text/plain
Date: Mon, 25 Sep 2017 00:00:00 GMT

this person has not selected a spirit animal

Dato che stai creando un'interfaccia di programmazione, non un'interfaccia umana, il testo 404 è facoltativo.

Preferisco questo perché preferisco i protocolli standard il più possibile. HTTP ha un modo per rappresentare la non-esistenza, ed è quello che vorrei usare.

MODIFICA: Supponi di aver aggiunto una funzione in cui gli utenti possono scegliere se condividere i loro animali spirituali e qualcuno non lo condivide. Restituiresti 200 OK nullo 200 OK "Unauthorized? O useresti lo standard 401 non autorizzato / 403 proibito? Questo sembra direttamente analogo al non sceglierne uno in primo luogo.

In alternativa, se si desidera utilizzare 200 OK + JSON, è necessario tornare null.

HTTP/1.1 200 OK
Content-Type: application/json
Date: Mon, 25 Sep 2017 00:00:00 GMT

"mole"

HTTP/1.1 200 OK
Content-Type: application/json
Date: Mon, 25 Sep 2017 00:00:00 GMT

null

Mantieni le cose pulite. Crea più avvolgimenti solo se necessario.