REST APIs Explained in 5 mins
There are already so many technical definitions of what is a REST API. However, most definitions are not very understandable. This post tries to explain what a REST API is and what pain point it solves in simple English.
Background
One way to make any web app work is to create the data embedded UI at the server side and pass the whole UI in the form of HTML to the client. One can use a templating language like EJS or PUG to generate HTML code on the backend server.
However, not every client wants the response in the form of an HTML template. Think about mobile apps which do not use HTML. We might want to create service APIs to third party applications just like Google maps does. One does not have any clue about their user interface. One only needs the data and the client is expected to fill this data in the interface generated by the itself.
Mobile apps might want to use different libraries from Java, Swift, Objective C etc. Web apps might want to use Angular.js, Vue.js or React.js Thus, deciding the UI at the backend might not be a good decision. Also, service apis to third party applications do not require the user interface, they just require the data.
Also, these days SPAs (Single page apps) are used at the client side. They do not expect the URL to change for changing the UI. It makes the user experience bad. They just need to use browser rendered javascript to change the UI. You click around then you don’t wait for page refresh. Data interaction and population happens in the background.
Thus, the problem we understood so far is the problem that UI and data need to be decoupled so that data can be used across multiple client side platforms.
A different kind of response is needed from backend. We need to transfer data instead of UI. We leave it to the client (mobile, SPA, third party application) to do whatever it wants to do with the data.
REST (Representational State Transfer).
A client-server architecture is made up of requests, responses and resources. Resource is the target of the HTTP request on which an action is requested. It can be an entry in DB, an image, a document or anything. A client makes an operation on a resource through an HTTP request and expects a response giving information about execution of the desired action on resource.
Now, in which format to expect the data from server. Below is the diagram showing the different type of data formats which can be rendered by an API response with their unique characteristics.
The most suited data format for the REST APIs is the JSON (Javascript Object Notation). This allows one to get structured data which is concise and easily readable by machine as well as by humans. Also, it can be easily converted to a JS object and JS is what runs in the browser eventually.
We know from our previous knowledge, what an API (Application Programming Interface) is. It is a contract between an information provider and an information user with a set definitions and protocols. In other words, if you want to interact with a computer or system to retrieve information or perform a function, an API helps you communicate what you want that system to do so it can understand and fulfil the request.
Now let’s understand what an API endpoint is. An API endpoint is a combination of an HTTP URL and an HTTP verb. An HTTP verb defines the nature of the request. What change on the resource will the request bring? Will it just fetch the resource, create a resource, modify it, replace it and so on?
Thus, GET https://example.com?user_id=1 is an endpoint. It represents that we want to get the resource with user_id 1 from the url which represents example.com server.
The following infographic shows the different HTTP verbs with their use cases.
Using the right verb makes the API endpoint more predictable. Although, it is only a matter of convention. You many use any verb and execute the code of your choice on the server. You may make a GET request create an entry in database. That is perfectly possible. But it will only create confusion to the client as he would not be able to predict the behaviour of the API endpoint.
Now let’s come to the definition. When a client makes a request via a RESTful API, it transfers a representation of the state of the resource from the client to the server. The state can mean information about the client ie who the client is, what is he authorised to do, which resource is he requesting to get or change on the server, what changes he wants to do on that etc.
The server does not know beforehand who the client is, when he last requested any resource. Each request is un-connected to the previous request and no session of the user is maintained at the server side. For cases where maintaining information related to user is essential especially related to user’s identity, JWT tokens are used by the client in auth headers to authenticate and authorise itself. The tokens are again stored at the client and not at the server. The server only generates or verifies the token, but never stores it. Thus, REST API is totally stateless.
The REST convention profusely makes use of headers to transfer meta data about the resource. All the authorisation tokens, what kind of response to expect in terms or format etc are all communicated through request and response headers.
Finally to summarise, following are the main principles of REST architecture:
- A client-server architecture made up of clients, servers, and resources, with requests managed through HTTP
- Stateless client-server communication, meaning no client information is stored between get requests and each request is separate and unconnected.
- Uniform interface: Clearly defined API endpoints, and request and response data structure. One is able to exactly define the state of the resource in the client request.
- Layered system: The server may forward the HTTP request to other servers and the client would not have visibility to that
- Cacheable data that streamlines client-server interactions. The data sent by the server to the client can be cached and once it expires, the data can be requested again
- Code-on-demand (optional): the ability to send executable code from the server to the client when requested, extending client functionality. However, it is used very rarely.
Conclusion
RESTful architecture by far the most popular in today’s times. Very much used, very much spoken about, however now very well understood. This post is an attempt to explain the REST principles in the simplest language possible. If you like this post and find it relevant please give some claps on medium and share it with relevant people. Thanks you very much for reading this!!
