What is "representation", "state" and "transfer" in Representational State Transfer (REST)?
REST is about resource state manipulation through their representations on the top of stateless communication between client and server. It's a protocol independent architectural style but, in practice, it's commonly implemented on the top of the HTTP protocol.
When designing REST over HTTP, URLs are used to locate the resources, HTTP methods are used to express the operations over the resources and representations such as JSON and/or XML documents are used to represent the state of the resource. HTTP headers can be used to exchange some metadata about the request and response while HTTP status code are used to inform the client regarding the status of the operation.
What is a resource in my example?
Understand resource as the concept of a user. Don't think about the table in your database, think about an abstraction of a user with their set of attributes.
What is a representation in my example?
A JSON document can be used to represent the state of a particular resource. A resource can have many representations, such as JSON and/or XML documents, and the client can use content negotiation to request different representations of the same resource.
What is a state transfer or when does this happens in my example?
The state of a given resource can be retrieved and manipulated using representations.
A GET request, for example, allows you to retrieve a representation of the state of a resource, sent in the response payload. A PUT request, for example, allows you to replace the state of a resource with the state defined by the representation enclosed in the request payload.
Example
Consider a user resource with attributes such as id and name stored somehow in your server:
- ID: 1
- Name: John Doe
These details make the state of the resource.
A URL such as /users/1 can be used to locate the resource in your server.
Requests such as GET, PUT and DELETE can be performed against this URL to retrieve/manipulate the state of the resource using representations, such as JSON and/or XML documents (other representations can be supported according to your needs):
{
"id": 1,
"name": "John Doe"
}
<user>
<id>1</id>
<name>John Doe</name>
</user>
The above shown documents are not the resource itself. They are just a way to represent the resource. which is stored somehow in your server.
If you want to understand REST, you should really start from the source: Fielding's thesis.
What is a Resource in my example?
OK, review of the term:
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.
In other words, the "resource" is the concept you are talking about. In this case, the user with name xxx. But it could be anything - the table that holds the data about the user with name xxx is also a "resource".
What is a Representation in my example?
Representations are fundamentally byte arrays
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.
So your json document -- more precisely, the utf-8 encoded byte array, is a representation. A given resource might have many representations at any given time.
What is a state transfer or when does this happens in my example?
When the client and server exchange messages; the client server architectural style is the first of the architectural constraints in the REST architectural style.