Ma réponse JSON doit-elle contenir la valeur du paramètre de requête de requête?

Question

Dois-je inclure le paramètre de requête d'entrée dans la réponse?

Disons que j'ai un point de terminaison qui renvoie les noms des personnes. Je permets à mon client de filtrer le résultat par pays.

Je me demande, dois-je inclure la propriété country dans la réponse ou non, même si elle correspond à ce que le client a demandé.

Par exemple, lorsque l'utilisateur envoie la requête ci-dessous

/personnes? Country = UK

dois-je retourner

[{"name":"tom"},{"name"="tim"}] 

ou

[{"name":"tom","country":"UK"},{"name":"tim","country":"UK"}] 

comme réponse?

Answer 1

Dépend des données dont le client a besoin.

Si vous voulez juste un moyen de dire au client ce qu'il a demandé, vous pourriez avoir une convention dans votre API sur le fait qu'un nœud de haut niveau montre quels sont les paramètres de la requête qui ont généré cette réponse.

{"requestParams":"country=UK&city=London", data: [{"name":"tom", "street":"Wallaby"}, {"name":"tim", "street":"West"}]

Mais vous ne voulez certainement pas risquer de retourner des informations sensibles en retournant les params de demande.

Answer 2

Afin de répondre à votre question, nous devrions d'abord clarifier l'intention réelle derrière REST car cela est souvent mal conçu. REST ne concerne pas les URI propres ou les API de type buzzword, il s'agit de découpler les clients de serveurs similaires aux navigateurs Web qui sont assez robustes et qui ne perturbent guère les changements de serveur. Pour ce faire, le client ne doit pas avoir d'hypothèses ou de connaissances prédéfinies sur une API ou ses ressources. Tout ce qu'il doit savoir doit être appris via l'interaction demande-réponse. Ce n'est pas facile à réaliser mais cela garantit que le client ne se cassera pas sur les changements effectués côté serveur. Par conséquent, le serveur doit inclure des liens (HATEOAS) qu'un client peut utiliser pour effectuer un changement d'état lors de l'appel de ces URI. Le protocole de sauvegarde (souvent HTTP) définit les verbes (ou méthodes) que vous pouvez utiliser sur ces URI. Pour éviter de coupler un client à un serveur, le client peut envoyer une liste connue de formats de document pris en charge (comme text/html dans un navigateur Web) au serveur, et le serveur peut choisir l'un des types de document pris en charge et convertir l'état de la ressource à ce format (si supporté). Ce type de contenu définit maintenant ce qui est renvoyé au client. Cela peut être le contenu complet de la ressource juste convertie en la représentation respective (d'où le transfert d'état représentationnel, REST) ​​ou peut être juste une sous-vue de certains des états de ressources.

Il existe déjà une variété de définitions de type de contenu disponibles, mais les fournisseurs d'API peuvent créer leurs propres définitions ou en étendre d'autres si nécessaire. L'inconvénient des types de contenu personnalisés est, cependant, que les clients doivent apprendre ces types de contenu d'une manière ou d'une autre.Types de supports sont bien la base de connaissances réelles des clients RESTful et Roy Fielding a également déclaré que la plupart de l'effort de conception devrait être mis en types de médias spécialisés et leur manipulation:

Une API REST devrait passer la quasi-totalité de ses efforts descriptif en définissant le (s) type (s) de média utilisé (s) pour représenter les ressources et piloter l'état de l'application, ou pour définir des noms de relations étendues et/ou un marquage hypertexte pour les types de média standard existants. Tout effort consacré à décrire les méthodes à utiliser sur les URI d'intérêt devrait être entièrement défini dans le cadre des règles de traitement pour un type de média (et, dans la plupart des cas, déjà défini par les types de média existants). [Un échec implique qu'au lieu hors bande information conduite interaction de l'hypertexte.] (Roy Fielding)

Alors que application/xml et application/json sont très populaires et largement pris en charge, ils ne transmettent pas la sémantique beaucoup. Quelque chose comme application/atom+xml ou application/hal+json prend au moins en charge les liens pour prendre en charge les exigences HATEOAS. Donc, pour être vraiment RESTful, vous devez réutiliser un type de contenu existant comme vCard pour vos informations people ou concevoir quelque chose de nouveau et le rendre accessible au public afin que les clients-implémenteurs aient un moyen d'apprendre le la gestion de ces types de contenu. Le type de contenu vcard commun définira déjà ce que vous pouvez retourner lorsque vous êtes sur le type de contenu personnalisé, vous êtes littéralement libre de retourner ce que vous voulez, mais au moins un client qui supporte ce type de contenu pourra traiter les données plus loin.

Answer 3

Je dirais simplement que vous devriez choisir une représentation minimale de vos articles à envoyer avec des réponses de collecte, et être cohérent dans le renvoi de ceux-ci. Étant donné que la valeur de la requête dépendra toujours des données sous-jacentes des éléments qui retournent, ces données doivent figurer dans les représentations que vous renvoyez lorsque les éléments individuels sont demandés (par exemple/people/tom). include {"country:" UK "}. Décidez simplement quelles parties de l'élément complet vous voulez inclure dans la liste

Si une requête est fournie qui filtre sur une propriété qui n'est pas dans votre représentation minimale habituelle de" Si cela fait normalement partie des données de personne que vous incluez dans un appel à/people? foo, alors incluez-le quand même