Dans le langage REST, quelle est la différence entre une ressource et une représentation?

Ma compréhension de REST qui permet de modéliser les opérations de service comme représentation de l'état et transition d'un état à un autre en utilisant HTTP. J'ai toujours compris les ressources comme des représentations de l'état du service jusqu'à récemment lorsque j'ai lu cet article de Jimmy Bogard que je sais être un développeur / architecte intelligent bien respecté par la communauté. Pour citer une déclaration spécifique de ce poste

La représentation est un peu différente - elle décrit l' état actuel de la ressource (sur demande).

Cela m'a laissé perplexe. Quelle est l'opinion généralement acceptée sur le sujet?

Réponse courte

La carte n'est pas le territoire.

Réponse plus longue - comme pour tout REST, le point de départ est la thèse de Roy Fielding ; en particulier le chapitre 5 . Pour votre question actuelle, vous voulez la section 5.2.1.

REST est défini par quatre contraintes d'interface: identification des ressources; manipulation des ressources à travers des représentations; messages auto-descriptifs; et hypermédia comme moteur de l'état d'application.

Ressource

L'abstraction clé des informations dans REST est une ressource. Toute information pouvant être nommée peut être une ressource: un document ou une image, un service temporel (par exemple «la météo d'aujourd'hui à Los Angeles»), une collection d'autres ressources, un objet non virtuel (par exemple une personne), etc. . En d'autres termes, tout concept qui pourrait être la cible de la référence hypertexte d'un auteur doit s'inscrire dans la définition d'une ressource. Une ressource est un mappage conceptuel sur un ensemble d'entités, et non l'entité qui correspond au mappage à un moment donné dans le temps.

Représentation

Les composants REST effectuent des actions sur une ressource en utilisant une représentation pour capturer l'état actuel ou prévu de cette ressource et en transférant cette représentation entre les composants. Une représentation est une séquence d'octets, plus des métadonnées de représentation pour décrire ces octets. D'autres noms couramment utilisés mais moins précis pour une représentation incluent: document, fichier et entité, instance ou variante de message HTTP.

Une représentation se compose de données, de métadonnées décrivant les données et, à l'occasion, de métadonnées pour décrire les métadonnées (généralement dans le but de vérifier l'intégrité du message).

Donc: "la météo d'aujourd'hui à Los Angeles" est une ressource. Les représentations des candidats comprendraient: un document texte contenant les dernières prévisions du service météorologique national; une représentation visuelle du radar météorologique et un enregistrement audio des prévisions.

Une ressource est la chose avec laquelle vous travaillez. Par exemple, si vous avez une API pour changer une certaine lampe, alors la ressource est la lampe elle-même. Une ressource peut être physique (par exemple lampe, personne) ou non physique (par exemple article, rôle, une ligne dans la base de données), une ressource peut être principale (par exemple solde) ou dérivée (par exemple transaction). Une ressource peut faire référence à une entité spécifique (par exemple la cinquième lampe installée dans cette douille de lampe), ou elle peut faire référence à un rôle qui correspond à une entité différente à un moment différent (par exemple la lampe actuellement installée, la lampe installée le 5 août 2008) ou il peut correspondre à plusieurs entités (par exemple, toutes les lampes de la maison).

La représentation d'une ressource est la façon dont votre service communique l'état de la ressource, par exemple XML, JSON qui représente l'état de la lampe.

Dans l'API REST, une ressource est identifiée par un identifiant uniforme (par exemple URI). Une seule ressource peut avoir plusieurs représentations, dans l'API HTTP REST, vous devez normalement indiquer la représentation que vous souhaitez utiliser dans les en-têtes HTTP Content-Type et Accept.

L'une des principales réalisations de l'architecture client-serveur est que vous ne pouvez pas apporter la ressource au client et que vous ne devriez pas essayer de la faire comme vous le faites. Au lieu de cela, dans l'API REST, vous manipulez une ressource à distance en transférant des représentations de la ressource. Pensez à cela, vous ne FedEx pas la lampe afin que le client puisse manipuler la lampe directement, mais le service crée plutôt une représentation XML / JSON / protobuf / CSV de la lampe et le client envoie une représentation des manipulations prévues. Le service manipule ensuite l'état réel de la lampe au nom du client, ou rejette la demande, par exemple si le client n'est pas autorisé à effectuer les opérations sur la lampe. Cela peut sembler évident / couper les cheveux, mais la chose importante à noter est que, puisque la représentation n'est pas la ressource elle-même,

Une ressource peut être une facture.

Une représentation est une facture à un moment précis au format JSON ou au format XML. Vous pourriez obtenir la même facture à une date ultérieure, ce sera la même ressource mais dans un état potentiellement différent (annulé, payé, etc.).

Vous prenez l'état actuel de la facture (par exemple: toutes les données de facture dans la base de données) et lui donnez une représentation spécifique (par exemple: html, xml, json) à un moment précis, pour le transfert vers un autre appareil (par exemple: un navigateur)