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 du discours j'ai commencé à me demander. Nous développons notre API HTTP JSON publique à mon travail, et nous ne retournons rien quand ce n'est pas strictement nécessaire (par exemple, un PUT vers/resource/{id} ne renvoie que 200 lorsque OK ou le code 4XX ou 5XX correspondant, mais non Corps JSON)
Faut-il retourner un générique {"success":true} comme ils discutent sur ce lien ci-dessus, ou est-ce correct de renvoyer un corps "vide" et de tout gérer avec les codes de réponse http?
En ce qui concerne PUT, mais s'applique également à POST. La section spécification HTTP 9 est un peu vide sur les règles ou même les conseils (DEVRAIT) quand il s'agit du scénario qui vous décrivez. La ligne pertinente à votre question est le plus étroitement couverte par:
Si une nouvelle ressource est créée, le serveur d'origine DOIT en informer l'agent utilisateur via la réponse 201 (créée). 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 la réussite de la demande.
Je ne pense pas que je perdrais le sommeil dessus, mais je demanderais, que gagnez-vous en ajoutant le morceau de JSON dans la réponse? Vous venez de compléter (OK, peut-être trop!) La réponse répétant moins précisément ce que le code d'état aurait déjà dû vous dire. Si votre PUT a abouti à un nouveau retour d'objet 201 (comme l'intention de PUT), s'il a mis à jour un retour d'objet 204.
Soit dit en passant, l'API de côté, au lieu de 200, si vous ne retournez rien, utilisez 204.
En supposant que vous développez un ensemble d'interfaces RESTful, il n'y a pas de standard en soi, donc quoi que vous fassiez, documentez-le bien, fournissez des exemples et tout ira bien.
La norme HTTP de base n'exige pas qu'un document soit renvoyé avec une réponse. Par souci d'économie, lorsqu'un statut HTTP transmet tout ce qui est requis, le corps serait un gaspillage. Cependant, il existe des normes basées sur HTTP qui ajoutent de nouvelles règles.
Il y a un open norme API JSON qui spécifie:
- Un objet JSON [~ # ~] doit [~ # ~] être à la racine de chaque API JSON réponse document. (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 c'est un travail en cours. Au mieux, je l'utiliserais comme guide.
Certaines applications (comme ElasticSearch ) fournissent une API JSON complète et ont toujours des métadonnées pour 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 indique la santé de l'index, si la demande a entraîné une erreur, le nombre de nœuds affectés, etc. ElasticSearch utilise "application/json" pour le type mime, il est donc peu probable qu'ils appliquent les directives de la norme jsonapi.org.
JQuery et les frameworks Javascript similaires supposent qu'il y aura toujours un document. La question est de savoir combien de vérifications d'erreurs voulez-vous imposer à vos clients API? Si vous proposez un format standard pour toutes les réponses qui n'est étendu qu'en fonction du type de demande, vous répondez au besoin d'un document de retour et pouvez faciliter le débogage par vos consommateurs 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 soulève une erreur. Je comprends en quelque sorte l'argument selon lequel, 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 des json valides.
Il existe un autre moyen qui devrait fonctionner pour jquery, qui ne renvoie pas 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.
Note Je ne me souviens que de 204 pour avoir explicitement interdit de retourner le corps du message. Ce que nous avons découvert, c'est que nous ne pouvons pas toujours utiliser 204. Le problème est l'en-tête MSIE drop response pour 204 réponses, donc il n'y a pas d'en-têtes de contenu et , ce qui est mauvais. Étant donné que beaucoup utilisent MSIE, nous avons dû le changer en 200.
Non, mais cela aidera à la cohérence de votre code. Il est également bon pour le débogage. Il sera également d'une grande aide dans 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 juste minime (seulement quelques octets envoyés sur le réseau) par rapport à ses avantages. Autre chose, cela vous évitera également d'oublier d'écrire un corps de message lorsque cela est nécessaire.
Je ne retournerais pas simplement un statut de réussite dans la réponse, le code d'erreur http ne signale que le succès ou l'erreur. J'inclurais uniquement l'utilisation de la réponse elle-même pour ajouter des informations d'erreur détaillées telles que des codes d'erreur spécifiques à l'application ou des messages d'erreur.
Pour les requêtes PUT, PATCH et POST, vous retournez généralement l'état renvoie l'état de la ressource après l'application de la demande, pas une réponse vide.
Pour les requêtes POST qui représentent une action au lieu de simplement créer une ressource (pas très RESTful, mais toujours utile en pratique), qui n'a pas de données utiles à renvoyer, je retournerais une réponse consistant en un objet json vide, c'est-à-dire {}. De cette façon, le client obtient une réponse valide et l'ajout d'informations plus tard ne risque pas de le casser.
Pour les demandes DELETE renvoyant 204 et un corps vide est assez courant, ce qui est logique puisque la ressource n'existe plus par la suite.
Je suggère de ne renvoyer que ce qui est nécessaire + un petit éclaircissement.
Par exemple, selon la façon dont votre API doit être utilisée, vous pouvez inclure une copie de l'objet, telle qu'elle existe après avoir été enregistrée.
Ainsi, un POST de {key: 123} peut retourner {key: 123, foo: 'bar'}.
L'idée de base est qu'il vaut mieux renvoyer l'objet que d'avoir à le rechercher à nouveau.
Cela dit, de vos clients API 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 réception. Cela dit, il vaut mieux 99% des le temps de renvoyer la représentation enregistrée de l'objet, il est rare qu'ils n'en aient pas besoin de toute façon, et c'est "moins cher" de tout envoyer en une seule demande puis en deux.
Pour être précis, dans un laboratoire, il est parfaitement utile de tout gérer avec des codes d'état, dans le monde réel, il est préférable de renvoyer certaines données, même si elles sont redondantes, afin que les consommateurs d'API puissent facilement comprendre ce que vous essayez de dire.
Renvoyer 200 {success: true} permet aux gens 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, (désolé pour la structure de réponse poos), en fournissant une API JSON publique, vous abandonnez beaucoup de contrôle sur la façon dont elle va être utilisée. Certains clients peuvent réagir différemment à différents organismes (ou en manquer) ou à des codes d'état.