L'API RESTful représente l'absence de chose

Imaginez une API pour identifier si une personne a sélectionné son animal spirituel. Ils ne peuvent avoir que zéro ou un animal spirituel.

Actuellement:

/person/{id}/selectedSpiritAnimal

quand ils ont sélectionné un animal retourne http 200 et {selectedAnimal:mole}

mais quand ils n'ont aucune sélection, il renvoie http 404.

Cela rend mon animal spirituel malheureux car nous représentons une préoccupation de domaine valide - n'ayant pas encore sélectionné un animal spirituel - comme une erreur HTTP.

De plus, en tant qu'entreprise - erm Sprit-Animal-Hampers-R-us - nous voulons savoir quand quelqu'un n'a pas de sélection afin que nous puissions les inciter.

Quelle est une meilleure réponse ici:

HTTP 200 et {selectedAnimal:null}

ou encore plus explicite

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

Ou vaut-il mieux retourner une 404? Comme un peu comme this image has not yet been uploadedlors de la visualisation d'une image en ligne serait un 404. this person has not selected a spirit animalpourrait être un 404

Cette question a été proposée en tant que doublon, mais elle concerne une URL par ailleurs valide qui est demandée lorsque l'application a été configurée pour ne pas autoriser la modification que l'URL représente.

Alors que je regarde ici comment on représente une ressource où l'absence de la ressource est significative. C'est-à-dire qu'il est valide pour le client de demander l'URL et la réponse est que vous avez réussi à demander la ressource qui représente une absence de chose.

Il ne s'agit donc pas d'une `` logique commerciale '' mais plutôt d'une circonstance où l'absence de chose a un sens (il se peut que beaucoup de mes collègues soutiennent que 404 est toujours correct) mais je ne sais pas comment faire correspondre cela au spec.

Très difficile de choisir une réponse. J'ai changé d'avis plusieurs fois au cours de la conversation ici et de celle en cours au travail.

Ce qui m'arrange ici, c'est que la spécification dit qu'un 4xx, c'est quand le client s'est trompé . Dans ce cas, le client a été invité à attendre une réponse de l'URL selectedSpiritAnimal et n'a donc pas commis d'erreur.

Le consensus parmi mes collègues est que c'est le symptôme d'une mauvaise conception d'API

Il serait probablement préférable que nous demandions simplement / person / {id} et cela renvoie un ensemble de relations de lien pour la personne ... alors si vous ne recevez pas le lien / selectedSpiritAnimal (quand une personne n'a pas de sélection) mais vous appelez-le de toute façon alors un 404 a du sens. Ou que vous implémentiez des réponses partielles et que / person / {id} retourne un document plus complet à moins que le client ne demande un sous-ensemble des données

Les codes HTTP 4xx ne sont probablement pas le bon choix pour ce scénario. Vous déclarez que le fait d'avoir zéro animal spirituel est un état valide, et la route API person/{id}/selectedSpiritAnimaltiendra compte du fait que la personne en idpossède ou non.

Les réponses HTTP 4xx sont réservées à la situation où un client a fait quelque chose de incorrect dans la demande (voir l'archive w3 de la spécification d'origine ). Mais le client fait une demande valable, que la personne idait ou non un animal spirituel.

Je me penche donc vers les deuxièmes solutions en utilisant un corps JSON correctement formaté dans la réponse et un code HTTP 2xx.

Maintenant, si vous obtenez une telle demande et qu'il s'avère que personne idn'existe, un code 4xx a plus de sens.

Permettez-moi de vous présenter le modèle de maturité Richardson .

Votre problème est que vous représentez deux ressources comme une seule, où vous devriez vraiment avoir deux ressources qui ont une relation indiquée par l'hypermédia. Utiliser l'hypermédia pour décrire les relations est le glorieux niveau 3 de repos.

Votre personne doit vivre sous l'URI /person/{id}et l'animal doit vivre sous /spiritanimal/{id}. La personne doit indiquer qu'elle a un animal spirituel en utilisant un lien vers l'animal.

Imaginons une personne appelée Bob, qui a l'identifiant 123 et un animal spirituel Licorne.

GET /person/123

retournerais;

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

Maintenant, quiconque lit la personne 123 saura qu'il a un animal spirituel et a l'URI où il peut obtenir plus d'informations à ce sujet.

GET /spitiranimal/789

pourrait revenir

{
  "type": "Unicorn"
}

Imaginons maintenant une personne appelée Fred, qui a l'identifiant 456 et aucun animal spirituel.

GET /person/456

retournerais;

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

Maintenant, quiconque lit la personne 456 saura qu'il n'a pas d'animal spirituel, car il n'y a pas de lien. Il n'est pas nécessaire d'utiliser un code d'état HTTP pour représenter l'absence de relation.

Ceci est l'URL appropriée pour obtenir des animaux spirituels; par conséquent, une erreur 404 est inappropriée. 404 est pour représenter un problème technique, pas un problème logique.

La solution appropriée consiste à renvoyer http 200 et {"selectedAnimal": null}

Vous devriez avoir une méthode Web séparée/person/{id}/hasSelectedSpiritAnimal qui revient {"isSpiritAnimalSelected": false}. Dans les coulisses, il peut ou non faire les mêmes appels de méthode, renvoyant simplement false si null, mais c'est à lui de décider, pas au code consommateur.

Il est préférable d'éviter de combiner pour séparer les requêtes en une seule méthode Web sans raison impérieuse de le faire, même si les requêtes sont étroitement liées.

Ce que votre point final représente n'est pas seulement un animal; c'est un animal ou son absence. C'est une valeur mieux représentée par un Optional/ Maybe/ Nullable/ etc.

Les valeurs légitimes (comme dans 200 OK) peuvent donc être:

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

Je pourrais imaginer que la DELETEméthode, lorsqu'elle est appliquée sur le point de terminaison, peut définir 'selected'à falsenouveau, qui est, UNSET l'animal sélectionné.

Vous pouvez, bien sûr, déposer la 'selected'clé ici, elle n'est affichée que pour plus de clarté; string vs nullsuffit pour la distinction.

Vous devez utiliser 404.

Le code d'état 404 (Not Found) indique que le serveur d'origine n'a pas trouvé de représentation actuelle pour la ressource cible

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

Puisque vous créez une interface de programmation, pas une interface humaine, le texte 404 est facultatif.

Je préfère cela parce que je préfère autant que possible les protocoles standard. HTTP a un moyen de représenter la non-existence, et c'est ce que j'utiliserais.

EDIT: Supposons que vous ayez ajouté une fonctionnalité permettant aux utilisateurs de choisir de partager leurs animaux spirituels et que personne ne les partage. Souhaitez-vous retourner 200 OK nullou 200 OK "Unauthorized? Ou utiliseriez-vous le standard 401 Unauthorized / 403 Forbidden? Cela semble directement analogue à ne pas en choisir un en premier lieu.

Alternativement, si vous souhaitez utiliser 200 OK + JSON, vous devez revenir 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

Gardez les choses propres. Créez plus d'emballage seulement si nécessaire.