Une API HTTP doit-elle toujours renvoyer un corps?

Existe-t-il une sorte de norme concernant les réponses de l'API HTTP?

Après avoir lu ce fil de discussion, j'ai commencé à me poser des questions. Nous développons notre API JSON HTTP publique sur mon travail, et nous ne renvoyons rien si ce n’est pas strictement nécessaire (par exemple, un PUT vers / resource / {id} ne renvoie 200 que lorsque OK ou le code 4XX ou 5XX correspondant, mais aucun Corps JSON)

Devrions-nous renvoyer un générique, {"success":true}comme indiqué sur le lien ci-dessus, ou est-il possible de renvoyer un corps "vide" et de tout gérer avec des codes de réponse http?

En ce qui concerne PUT, mais s’applique également à POST. La section de spécification HTTP 9 est un peu vide en termes de règles ou même de conseils (DEVRAIT) en ce qui concerne le scénario que vous décrivez. La ligne correspondant à votre question est la plus étroitement couverte par:

Si une nouvelle ressource est créée, le serveur d'origine DOIT informer l'agent d'utilisateur via la réponse 201 (Créé). Si une ressource existante est modifiée, les codes de réponse 200 (OK) ou 204 (pas de contenu) DEVRAIENT être envoyés pour indiquer que la demande a été complétée avec succès.

Je ne pense pas que je perdrais le moindre sommeil à ce sujet, mais je vous demanderais, que gagnez-vous en ajoutant le bloc JSON dans la réponse? Vous venez juste d’agrandir (OK, encombré, c’est peut-être excessif!), La réponse répétant avec moins de précision ce que le code de statut aurait déjà dû vous dire. Si votre PUT a généré un nouveau retour d'objet 201 (comme c'est l'intention de PUT), s'il a mis à jour un retour d'objet 204.

Incidemment, API mise à part, au lieu de 200, si vous ne retournez rien, utilisez 204.

En supposant que vous développiez un ensemble d'interfaces RESTful, il n'y a pas de norme en tant que telle, alors quoi que vous fassiez, documentez-le bien, donnez des exemples et tout ira bien.

La norme HTTP de base n'exige pas qu'un document soit renvoyé avec une réponse. Pour des raisons d'économie, lorsqu'un statut HTTP transmet tout ce qui est nécessaire, le corps gaspille. Cependant, il existe des normes basées sur HTTP qui ajoutent de nouvelles règles.

Il existe une norme ouverte de l' API JSON qui spécifie:

• Un objet JSON DOIT être à la racine de chaque document de réponse de l' API JSON . (les italiques représentent ce que j'ai ajouté pour clarifier le texte)

Malheureusement, la norme ne spécifie pas comment représenter un document vide et il s’agit d’un travail en cours. Au mieux, je l'utiliserais comme une ligne directrice.

Certaines applications (comme ElasticSearch ) fournissent une API JSON complète et contiennent toujours des métadonnées afin que vous puissiez avoir une meilleure idée de la façon dont le serveur gère vos données. L'objet de réponse standard vous informe sur la santé de l'index, si la requête a généré une erreur, combien de nœuds ont été affectés, etc. ElasticSearch utilise "application / json" pour le type mime. Il est donc peu probable qu'ils appliquent les instructions le standard jsonapi.org.

JQuery et les frameworks Javascript similaires supposent qu'il y aura toujours un document. La question est combien de vérification d'erreur voulez-vous imposer à vos consommateurs d'API? Si vous proposez un format standard pour toutes les réponses étendu uniquement en fonction du type de demande, vous répondez au besoin d'un document de retour et pouvez faciliter le débogage par vos utilisateurs d'API.

Non, par exemple, pour 204 réponses, nous ne devons pas inclure le corps du message. {success | status | isSuccessful: true} est redondant.

En pratique (ou devrais-je dire dans une version ultérieure de jquery), une réponse vide pour le type de contenu application / json génère une erreur. Je comprends un peu l'argument voulant que, parce que c'est application / json, il doit avoir un corps json valide. Ainsi, une réponse vide pour le type de contenu application / json serait «null» ou «{}», qui sont valides.

Il existe un autre moyen qui devrait fonctionner pour jQuery, qui consiste à ne pas renvoyer application / json pour les réponses vides. Utilisez simplement text / plain ou quelque chose et assurez-vous que le client peut gérer ce type.

Remarque: je ne me souviens que de 204 pour interdire explicitement le renvoi du corps du message. Ce que nous avons constaté, c’est que nous ne pouvons pas toujours utiliser 204. Le problème est l’en-tête MSIE avec suppression de la réponse pour 204 réponses. Il n’ya donc pas de contenu ni d’en - têtes, ce qui est mauvais. Comme beaucoup utilisent MSIE, nous avons dû passer au statut 200.

Non, mais cela aidera à la cohérence de votre code. C'est aussi bon pour le débogage. Cela contribuera également beaucoup à la maintenance du site Web. Rappelez-vous ceci: Le code d'erreur est pour la machine, le message d'erreur est pour l'homme. Je vous suggère donc d'utiliser un corps de réponse. Quoi qu'il en soit, son effet négatif est minime (quelques octets envoyés sur le réseau) par rapport à ses avantages. Une autre chose, cela vous évitera également d'oublier d'écrire un corps de message lorsque cela est nécessaire.

Je ne renverrais pas simplement un statut de réussite dans la réponse, le code d'erreur http ne signalant que le succès ou l'erreur. J'utiliserais uniquement la réponse elle-même pour ajouter des informations d'erreur détaillées, telles que des codes d'erreur ou des messages d'erreur spécifiques à une application.

Pour les demandes PUT, PATCH et POST, vous renvoyez généralement l'état, et renvoyez l'état de la ressource une fois la demande appliquée, et non une réponse vide.

Pour les demandes POST qui représentent une action au lieu de simplement créer une ressource (pas très RESTful, mais toujours utile), qui n'ont pas de données utiles à renvoyer, je retournerais une réponse consistant en un objet json vide, ie {}. De cette façon, le client obtient une réponse valide et l'ajout ultérieur de certaines informations a peu de chances de la rompre.

Pour les demandes DELETE, renvoyer 204 et un corps vide est assez commun, ce qui est logique puisque la ressource n'existe plus par la suite.

Je suggérerais de ne rendre que ce qui est nécessaire + un petit éclaircissement.

Par exemple, selon l'utilisation de votre API, vous pouvez inclure une copie de l'objet, telle qu'elle existe après avoir été enregistrée.

Ainsi, un POST de {clé: 123} peut renvoyer {clé: 123, foo: 'bar'}.

L'idée de base est qu'il est préférable de retourner l'objet plutôt que de devoir le rechercher à nouveau.

Cela dit, de votre API, les utilisateurs n'ont pas besoin de l'objet, il n'est pas nécessaire de le retourner.

Je retourne généralement {success: true} ou quelque chose du genre, quand aucun objet n'est requis sur POST PUT et PATCH car cela facilite la tâche du destinataire. Cela dit, il vaut mieux 99% du temps pour renvoyer la représentation enregistrée de l'objet, il est rare qu'ils n'en aient pas besoin de toute façon, et il est "moins cher" d'envoyer tout cela en une demande puis en deux.

Pour être précis, dans un laboratoire, il est parfaitement indiqué de gérer tout avec des codes d’état. Dans le monde réel, il est bien mieux de renvoyer certaines données, même redondantes, afin que les utilisateurs d’API puissent facilement comprendre ce que vous essayez de dire.

Le renvoi de 200 {succès: true} permet aux utilisateurs d'écrire du code dans les deux sens:

if response.code == 200
  do stuff
end

et

if response.body.success
  do stuff
end

en plus, ce n'est pas si difficile à faire de votre côté.

Enfin, (pardon pour la structure de réponse des erreurs), en fournissant une API JSON publique, vous donnez beaucoup de contrôle sur la manière dont elle sera utilisée. Certains clients peuvent réagir différemment selon les organismes (ou leur absence) ou les codes de statut.