9

My understanding of REST that is enables modelling service operations as representation of state and transition from one state to another making use of HTTP. I have always understood resources as representations of service side state until recently when I read this article by Jimmy Bogard whom I know to be a smart developer/architect well respected by the community. To quote a specific statement from that post

The representation is a bit different – it describes the current state of the resource (when requested).

This has left me confused. What is the generally accepted opinion on the topic?

  • 1
    You might want to check out: What topics can I ask about here?. Opinion polls are not on topic for Programmers.SE. – Adam Zuckerman May 22 '16 at 18:19
  • 2
    Well, everything listed on that page has no answer in black and white but all opinions. Also, I am not sure how this question is about opinion. Is it just because I used the word "opinion" in my question? – Suhas May 22 '16 at 20:07
  • Primarily, yes. Unfortunately (or perhaps fortunately), the words "opinion," "best practice" and the like have been associated strongly with "an empty resonant cavity where a brain should be," as most folks who use such terms merely want to spot a herd in the distance and go trotting off after it. People seeking word definitions are often the worst offenders. What specific problem are you trying to solve? – Robert Harvey May 22 '16 at 20:58
  • 1
    As to your question, a resource is merely "something out on the internet with an address," while a representation is "the manner that the thing on the internet is re-presented." It can be a file, a web page or a JSON document. It can be a specific kind of file, like a Word document or a spreadsheet. In all of these cases, the representation is that thing that you are retrieving. "The current state of the resource" is a recognition that the thing may have changed since the last time you retrieved it. – Robert Harvey May 22 '16 at 21:00
12

Short answer

The map is not the territory.

Longer answer - as with anything REST, the place to start is with Roy Fielding's thesis; in particular chapter 5. For your current question, you want section 5.2.1.

REST is defined by four interface constraints: identification of resources; manipulation of resources through representations; self-descriptive messages; and, hypermedia as the engine of application state.

Resource

The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. "today's weather in Los Angeles"), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author's hypertext reference must fit within the definition of a resource. A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time.

Representation

REST components perform actions on a resource by using a representation to capture the current or intended state of that resource and transferring that representation between components. A representation is a sequence of bytes, plus representation metadata to describe those bytes. Other commonly used but less precise names for a representation include: document, file, and HTTP message entity, instance, or variant.

A representation consists of data, metadata describing the data, and, on occasion, metadata to describe the metadata (usually for the purpose of verifying message integrity).

So: "today's weather in Los Angeles" is a resource. Candidate representations would include: a text document with the latest forecast from the national weather service; a visual representation of the weather radar, and audio recording of the forecast.

1

A resource might be an invoice.

A representation is an invoice at a specific point in time in JSON format, or in XML format. You might get the exact same invoice at a later date it will be the same resource but in a potentially different state (cancelled, paid, etc).

You take the current state of the invoice (eg: all the invoice data in the database) and give it a specific representation (eg: html, xml, json) at a specific point in time, for transfer to some other device (eg: a browser)

1

A resource is the thing that you are working with. For example, if you have an API for switching a certain lamp, then the resource is the lamp itself. A resource can be physical (e.g. lamp, person) or non physical (e.g. article, role, a row in the database), a resource can be primary (e.g. balance) or derived (e.g. transaction). A resource can refer to a specific entity (e.g. the fifth lamp installed in this lamp socket), or it can refer to a role that maps to different entity at different time (e.g. the currently installed lamp, the lamp installed on 5th August 2008) or it can map to multiple entities (e.g. all lamps in the house).

The representation of a resource is the way that your service communicates the state of the resource, e.g. XML, JSON that represents the state of the lamp.

In REST API, a resource is identified by a uniform identifier (e.g. URI). A single resource can have multiple representations, in HTTP REST API you'd normally indicate the representation you want to use in the HTTP Content-Type and Accept headers.

One key realizations in client server architecture is that you cannot bring the resource to the client, and you shouldn't try to make it like you do. Instead, in REST API, you remotely manipulate a resource by transferring representations of the resource. Think of this like, you don't FedEx the lamp so that the client can manipulate the lamp directly, but rather the service create an XML/JSON/protobuf/CSV representation of the lamp and the client send a representation of the intended manipulations. The service then manipulates the actual state of the lamp on behalf of the client, or reject the request, say if the client isn't authorized to do the operations on the lamp. This might seem obvious/splitting hair, but the important thing to note is that since the representation is not the resource itself, the representation can get out of date with the state of the resource.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.