web-dev-qa-db-fra.com

"Meilleure" pratique pour une réponse reposante POST

Donc, rien de nouveau ici, j'essaie simplement d'obtenir des éclaircissements et n'arrive pas à en trouver dans d'autres messages.

Je suis en train de créer une nouvelle ressource, par exemple:

/books (POST)

avec un corps:

{
  title: 'The Lion, the Witch and the Wardrobe',
  author: 'C. S. Lewis'
}

Je sais que je devrais renvoyer un 201 (Créé) avec un en-tête Location de la nouvelle ressource:

Location: /books/12345

La question à laquelle je n'arrive pas à répondre personnellement est de savoir ce que le serveur devrait retourner dans le corps.

J'ai souvent fait ce type de réponse:

{
  id: 12345,
  title: 'The Lion, the Witch and the Wardrobe',
  author: 'C. S. Lewis'
}

J'ai fait cela pour plusieurs raisons:

  1. J'ai écrit api pour les frameworks front end tels que angularjs. Dans mon cas particulier, j'utilise angular resources et je n'ai souvent besoin que de l'ID de la ressource pour la localiser. Si je ne renvoyais pas l'identifiant dans le corps de la réponse, je devrais l'analyser à partir de l'en-tête Location.
  2. Dans un GET de tous les livres, je retourne généralement l'objet entier, pas seulement l'identifiant. En ce sens, mon code client ne doit pas différencier où obtenir l'identifiant (en-tête ou corps de l'emplacement).

Maintenant, je sais que je suis vraiment dans la zone grise, mais la plupart des gens disent que restituer toute la ressource est une "mauvaise" pratique. Mais que se passe-t-il si le serveur modifie/ajoute des informations à la ressource? Il ajoute définitivement l'id, mais pourrait aussi ajouter d'autres choses comme un horodatage. Au cas où je ne renverrais pas la totalité de la ressource, est-il préférable de faire un post, de renvoyer l'ID, puis de demander au client d'effectuer une opération GET pour obtenir la nouvelle ressource.

restangularjsangularjs-resource
185
lostintranslation

Renvoyer l'intégralité de l'objet dans une mise à jour ne semblerait pas très pertinent, mais je ne vois pas très bien pourquoi le renvoi de l'intégralité de l'objet à sa création serait une mauvaise pratique dans les cas d'utilisation normale. Cela serait utile au moins pour obtenir facilement l’ID et les horodatages, le cas échéant. C'est en fait le comportement par défaut obtenu lors de l'échafaudage avec Rails.

Je ne vois vraiment aucun avantage à renvoyer uniquement l'ID et à faire une demande GET après, pour obtenir les données que vous auriez pu obtenir avec votre POST initial.

Quoi qu'il en soit, tant que votre API est cohérente, je pense que vous devez choisir le modèle qui correspond le mieux à vos besoins. Il n’existe pas de méthode correcte pour créer une API REST, imo.

111
Daniel Perez

Le renvoi du nouvel objet est conforme au principe REST de "Interface uniforme - Manipulation de ressources via des représentations". L'objet complet est la représentation du nouvel état de l'objet créé.

Il existe une excellente référence pour la conception des API, ici: Meilleures pratiques pour la conception d’une API RESTful pragmatique

Il comprend une réponse à votre question ici: Les mises à jour et la création devraient renvoyer une représentation de ressource

Ça dit:

Pour éviter qu'un consommateur d'API n'ait à demander à nouveau à l'API une représentation mise à jour, demandez à l'API de renvoyer la représentation mise à jour (ou créée) dans le cadre de la réponse.

Cela me semble bien pragmatique et cela correspond au principe REST que j'ai mentionné ci-dessus.

178
grahamesd