Let’s do some ReST
It is a software architectural style to define interfaces in a client server architecture.
Oops!!
Apologies, I am not talking anything about relaxation, if you thought so. I am talking about Representational State Transfer a.k.a ReST. You must have heard statements from architects or developers in your company that we are creating ReSTful services, or our service interfaces are ReSTful or we are designing ReST services.
It all means same that the web service is providing interfaces, which are following ReST defined guidelines. In other words, a user or software client can access capabilities provided by the web service using these ReST based interfaces.
For example:
If you are accessing LinkedIn, internally, there are lot of background calls made using ReST APIs (Application Programming Interface) to the web services deployed on some remote server to serve web pages to you.
OR,
If you are watching movie on Netflix, the movie content is served by using these ReST APIs from web services running in Amazon’s cloud.
This means ReST is widely used everywhere.
So, let’s understand about it more.
Basics Of ReST
When we are accessing any web site, we are mainly doing four tasks.
1. Downloading some data like file, picture, video etc.
2. Uploading some data
3. Updating some data
4. Deleting some data
The above four task, we achieve by using below four methods provided by HTTP protocol, which are used by all web sites and ReST too uses these methods.
1. HTTP GET – To download resource from web server to our device. This also includes web browsing, as when we browse, we download web pages, which are resources.
2. HTTP POST – To upload resource. Uploading a picture in Facebook, is a resource.
3. HTTP PUT – This method is used to update or create resource on the web server. Like updating your profile information.
4. HTTP DELETE – This is to delete resource on web server. Like deleting your Twitter account.
In terms of ReST, all the content, which is created on web servers are resources and it uses these methods to manipulate resources on the web server.
So, if you have noticed, all the methods are verbs because those are actions to be performed on resources and all resources are nouns, as those are things.
That means when we define a ReST interface, we need to be careful in choosing resources and its names. As we need to define resources as nouns and not as verbs. Otherwise, it will create issues during its interpretation, maintenance and in future extension of interface. How do you feel if instead of calling a monkey as monkey, we call him monkeying? 😊
Defining a proper resource in ReST requires good amount of thinking in right direction. For example: if you are defining a ReST interface to shut down or start up a system. You can define interface in following manner, which is completely WRONG.
- To start a System -> POST /Start OR POST /StartUp
- To Stop a system -> POST /Stop OR POST /ShutDown
Start and Stop are not resources, those are actions, those are verbs. Remember, resources are nouns. Also, StartUp and ShutDown can be treated as 2 resources, as those are nouns. But these are not good. In future, we can get requirement to restart the system. If resource is not defined properly, in future it may bloat and become unmanageable.
So, correct resource in this case can be “Power” and our ReST interface can be below ones.
- To start a System -> PUT /Power {State=ON}
Recommended by LinkedIn
- To stop a system -> PUT /Power {State=OFF}
In this case, there will be only resource “Power” and we are using PUT method to manipulate it. ON/OFF is passed as payload in it.
Let’s understand more about ReST
The full form of ReST is “Representational State Transfer”. Let’s break down this to understand this term better.
- Representational, means that we are representing a resource in some form (We will discuss form later).
- State, means the present state of resource
- Transfer, means transfer it in between server and client
This means using above HTTP methods, we are transferring a representation of current state of the resource.
Say, if you are downloading an article from world press, it can be represented in PDF format or in HTML format or in some other format, while you are downloading. It depends on which formats are supported by web server.
OR,
If you are uploading a picture in Instagram, it can be uploaded as JPEG or PNG or in some other format, depends on which formats are supported by Instagram web server.
But how a ReST server or client will know, which format they can support or use while transferring these resources. The answer is using media types.
There are several media types (or MIME types) are defined and ReST uses those while transferring the resources between server and client. Client sends a request of a resource along with its media type to server and if server supports that representation of the resource, then it will honor the request, otherwise it will reject the request and can provide its accepted media types for that resource.
Some commonly used media types are:
- application/pdf
- application/json
- application/xml
- application/zip
- image/jpeg
- text/plain
- text/html
Summary
ReST is a set of guidelines, which uses HTTP methods to act upon resources. The representation of the resource is transferred based on the media types supported by the server.
There is lot more to learn about it. If you are interested, then check resources 😊 in reference section.
References
Links
Books