What is the difference between resource and resour

Question

I am new to REST and just started reading some tutorials.

One thing that really confuses me is: what comes in txt/xml/json form: the resources or the resource representations? Must be the latter, right? Since resources can be a video, audio or other MIME types.

Take the example below. Let's say I am given a description like 'a RESTful service where User is a resource which is represented using the following XML format':

<user>
   <id>1</id>
   <name>Mahesh</name>
   <profession>Teacher</profession>
</user>

or JSON format:

{
   "id":1,
   "name":"Mahesh",
   "profession":"Teacher"
}

Then, when I use HTTP GET to access the resource, what data do I actually get back? Do I get '1, Mahesh, Teacher' since this is the real data excluding the format, or do I get the whole xml or json 'object' that contains both the data and the data representation?

What if User has an image property? What kind of 'package' and in which form will HTTP deliver it to me: the image itself or a link to the image?

EDIT

Another example here:

http://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&sensor=false

Here should I understand that the returned resource itself is an XML file, or the resource is NOT an XML file, but some data that's embedded in XML resource representation is?

And what if the resource I want contains images, videos, etc.? Those are not text data that can be embedded in XML or JSON format--in that case, what do I get?

Answer 1

Here are the words of the Godfather of REST, Roy T. Fielding (from his dissertation)

§ 5.2.1.1 Resources and Resource Identifiers

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... (There's more, click the link to read on).

Really a resource can be abstract concept that that is identifiable by a URI and can be represented in transmittable data.

§ 5.2.1.2 Representations

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.

[...]

The data format of a representation is known as a media type. A representation can be included in a message and processed by the recipient according to the control data of the message and the nature of the media type.

So really the representation is the data (or state) that represents the resource.

The data format of the representation is formally the media type, but you may also hear it being called the variant.

Everyone interested in REST, should at least read Chapter 5 of that dissertation. After all, it's how REST came to be.

Answer 2

With REST all depends on what representation (i.e. MIME format) you are requesting in your HTTP GET. There are e.g. HTTP headers to convey that. From the client's perspective it is always about representation(s) prior to the "raw" data.

The glory details are here.

So yes, you will "get the whole xml or json 'object' that contain both the data and the data representation".

Answer 3

Resource

The concept of a REST resource is abstract and you can understand it as something that is identified by a URL provided by the server.

The resource can be a user, a list of users, a customer, a file or any entity of the application.

For example, consider a user as your resource with the following attributes and values:

• ID: 1
• First name: John
• Last name: Doe
• e-mail: [e-mail]

URL

The URL (Uniform Resource Locator) just identifies the resource, that is, where the resource is located in the server.

For example, while the URL /app/users/1 locates the user with the ID 1, the URL /app/users locate all the users in the application.

HTTP methods

REST is protocol independent, but, if you are using HTTP, you can perform actions on the resource accessing the URL with HTTP methods, such as GET, POST, PUT and DELETE.

For example, when you perform a GET to the URL /app/users/1, you'll obtain a representation for the user with the ID 1.

Resource representation

A resource can be represented in multiple formats, such as JSON, XML, YAML, etc.

In JSON, the representation would be:

{
    "id": 1,
    "firstName": "John",
    "lastName": "Doe",
    "email": "[e-mail]"
}

In XML, the representation would be the following:

<user>
    <id>1</id>
    <firstName>John</firstName>
    <lastName>Doe</lastName>
    <email>[e-mail]</email>
</user>

---

Example 1

Consider you are developing an application in JavaScript and the server can provide a representation of the resources as JSON and XML. It's easier to deal with JSON rather than XML in JavaScript applications. So, you want the resources represented as JSON.

To do it, when performing a GET to the URL /app/users/1, you'll add the HTTP header Accept with the application/json value to tell the server the representation the client accepts.

Consequently, the server will return the resource represented as JSON. The response will contain the Content-Type header with the application/json value, indicating the content of the response is a JSON.

---

Example 2

Besides JSON and XML, for example, the resources can be represented as images or videos.

Consider a URL which locates the profile picture of a user: /app/users/1/profile-picture.

Depending the image type, the Content-Type of the response will be image/jpeg, image/png, image/gif, etc.

---

This answer may also be insightful.