Understanding RESTful architectural style

What exactly is RESTful?

Here are the articles and papers that helps my understanding of REST

RESTful is an architectural style for distributed hypermedia systems. It represents Representational State Transfer. Some key concepts before moving to RESTful are:

1. What make up a request

• The endpoint: is the url you request for. It follows this structure: root-endpoint/?
• The method: GET, POST, PUT, PATCH and DELETE. They are used to perform four possible actions: create, read, update and delete(CRUD)
• The headers
• The data (body)

2. What is a Resource

Resource means some entities in network or some type of information. It can be text, image, video, service, etc. But basically, it is some concrete exists. You could point to resources using URI and for each specific resource, there is a unique URI mapped to it. In order to get that resource, you just need to visit that URI.

3. What is Representation

Resource is a concrete exists, but it can have multiple types of representations. The way that a resource represents, we call it Representation. For instance, we have a text format resource. The representation of this resource can be "txt", "HTML", "XML", "JSON", etc. If we have a image, the representation of it can be "jpg", 'png', etc.

The way we define Representation in a request is through the HTTP request Head: Accept and Content-Type. Please note that URI does not represent the representation of the resource, and it only represents the concrete resource itself.

4. What is State Transfer

When user visiting some website, it means some interacitons between client-server. HTTP protocal is state-less means that all states are saved in server side. If we wanted to manipulate server-side, we need to use some ways(GET POST PUT DELETE PATCH) to make State Tranfer happen on server-side. And this State Transfer is based on the Representation of resource.

The design rules of RESTful API

Resources

For each resource in server, there is a URI pointing to it and by using this URI, user will have access to that resource. Instead of making our requests to each singular endpoint, we talk to resources.
One way of thinking of this is resources is object and it contains multiple endpoints (services) which more like functions/methods of this object.

//make request to resources thru URI
GET /user/abc

//Response
200 OK
Content-Type: application/json+userdb
[other headers]
									

HTTP verbs

When we interact with server through HTTP, we should use HTTP verbs as closely as possible to how they are used in HTTP itself. GET is a safe operation as it doest make status change in our resources and because of this, it will get us the same result each time as we perform this GET action to same resource. Because of this safety feature, it allows any requests to use caching to make website performs better. PUT and POST can change the state of resources.

Hypermedia

This term is under HATEOAS(Hypertext As The Engine Of Application State). It addresses that what are the next things we can do once we access to one resource. We can find information about related resources from "links". This is called Hypermedia Controls

GET /user

//Response
200 OK
Content-Type: application/json+userdb
{
	"links": [
	{
		"href": "/user",
		"rel": "list",
		"method": "GET"
	},
	{
		"href": "/user",
		"rel": "create",
		"method": "POST"
	}
	]
}

GET /user
200 OK
Content-Type: application/json+userdb

{
    "users": [
        {
            "id": 1,
            "name": "abc",
            "links": [
                {
                    "href": "/user/1",
                    "rel": "self",
                    "method": "GET"
                },
                {
                    "href": "/user/1",
                    "rel": "edit",
                    "method": "PUT"
                },
                {
                    "href": "/user/1",
                    "rel": "delete",
                    "method": "DELETE"
                }
            ]
        }
    ],
    "links": [
        {
            "href": "/user",
            "rel": "create",
            "method": "POST"
        }
    ]
}