Meilleure pratique pour une réponse POST reposante

Question

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

Je crée une nouvelle ressource en toute tranquillité, disons :

/books (POST)

avec un corps :

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

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

Location: /books/12345

La question à laquelle je ne parviens pas à répondre est de savoir ce que le serveur doit renvoyer dans le corps du message.

J'ai souvent eu recours à ce type de réponse :

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

Je l'ai fait pour plusieurs raisons :

1. J'ai écrit une api pour des frameworks frontaux comme angularjs. Dans mon cas particulier, j'utilise des ressources angulaires et j'ai souvent besoin de l'identifiant de la ressource pour la localiser. l'identifiant de la ressource pour la localiser. Si je ne renvoyais pas l'id dans dans le corps de la réponse, j'aurais besoin de l'analyser à partir de l'en-tête Location de l'en-tête.
2. Dans un GET de tous les livres, je renvoie généralement l'objet entier et pas seulement l'identifiant. Dans ce sens, mon code client n'a pas à différencier l'endroit où il doit obtenir l'identifiant (en-tête ou corps). l'endroit où il doit obtenir l'identifiant (en-tête de l'emplacement ou corps de l'objet).

Je sais que je suis vraiment dans une zone grise, mais la plupart des gens disent que renvoyer l'intégralité de la ressource est une "mauvaise" pratique. Mais que se passe-t-il si le serveur modifie/ajoute des informations à la ressource. Il ajoute certainement l'identifiant, mais il peut aussi ajouter d'autres choses comme un horodatage. Dans le cas où je ne renvoie pas l'intégralité de la ressource, est-il vraiment préférable de faire un POST, de renvoyer l'identifiant, puis de demander au client d'effectuer un GET pour obtenir la nouvelle ressource.

Answer 1

Le renvoi du nouvel objet est conforme au principe REST "Interface uniforme - Manipulation de ressources par le biais de représentations". L'objet complet est la représentation du nouvel état de l'objet qui a été créé.

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

La réponse à votre question se trouve ici : Les mises à jour et la création doivent renvoyer une représentation de la ressource

Il est écrit :

T représentation mise à jour, l'API doit renvoyer la représentation mise à jour (ou créée) dans le cadre de la réponse. dans le cadre de la réponse.

Cela me semble très pragmatique et correspond au principe REST que j'ai mentionné plus haut.

Answer 2

Renvoyer l'objet entier lors d'une mise à jour ne semble pas très pertinent, mais je ne vois pas pourquoi renvoyer l'objet entier lors de sa création serait une mauvaise pratique dans un cas d'utilisation normal. Cela serait utile au moins pour obtenir l'ID facilement et pour obtenir les horodatages lorsque c'est pertinent. C'est en fait le comportement par défaut obtenu lors de l'échafaudage avec Rails.

Je ne vois vraiment aucun avantage à ne renvoyer que l'ID et à effectuer une requête GET par la suite, 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 devriez choisir le modèle qui répond le mieux à vos besoins. Il n'y a pas de façon correcte de construire une API REST, je pense.

Answer 3

Après un article, j'aime renvoyer quelque chose comme ceci :

Response
   .created(URI("/obj/$id"))
   .entity(TheNewObj())
   .build()

Statut 201 - CRÉÉ

Emplacement de l'en-tête - l'emplacement du nouvel objet

Entité - le nouvel objet