json - What is the difference between resource and resource representation in REST?

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

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: john.doe@example.com

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": "john.doe@example.com"
}

In XML, the representation would be the following:

<user>
    <id>1</id>
    <firstName>John</firstName>
    <lastName>Doe</lastName>
    <email>john.doe@example.com</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.