What is a REST API ?

This content originally appeared on DEV Community and was authored by The Nerdy Dev

Hey everyone 👋🏻,

In this article, let us learn about one of the most important concepts that you as a backend developer must have a solid knowledge of (because anyways working with an API is a big part of your jobs) and that is REST APIs

REST APIs

Actual definition:

""
Representational state transfer (REST) is a software architectural style that was created to guide the design and development of the architecture for the World Wide Web. REST defines a set of constraints for how the architecture of an Internet-scale distributed hypermedia system, such as the Web, should behave. The REST architectural style emphasises the scalability of interactions between components, uniform interfaces, independent deployment of components, and the creation of a layered architecture to facilitate caching components to reduce user-perceived latency, enforce security, and encapsulate legacy systems.
""

Now you must be wondering : "What the heck does this mean ?"

Anyways, let us make it super simple and understand what a REST API is piece by piece.

Now before we understand why we use a REST API, we first need to understand what problems does it solve ?

REST APIs are there to solve one problem you can say that not every frontend (UI) requires HTML pages. Not every UI wants your server code to generate HTML pages which effectively is the UI.
Think about mobile apps these apps typically do not work with server side rendered HTML code. They do not need a templating language on server side to render the HTML code because you use a rich suite of prebuilt libraries for UI provided by Google or Apple to build your UI in the respective IDEs of these programming languages.

You build these User Interfaces totally decoupled from your server side logic. You don't want HTML code because you can't really render it there. Obviously you have browsers in your phone and that will render HTML pages.

But most of the applications do not use HTML to build their user interfaces but the tools that are provided by Google or by Apple and then you only need data to fill these user interfaces to life.

For building these amazing and sleek looking user interfaces on the frontend we have frontend technologies like React, Angular, Vue etc.

So we have a frontend that is decoupled from a certain backend logic like Google Maps (Server) and we only exchange data because we don't need the HTML code but just the data. We built the User Interface on our own. So we just need a backend server that can typically serve us just the data that we need and then we can easily fabricate our user interfaces as per our requirements.
So, this in essence is the core idea behind the REST APIs.

REST stands for Representational State Transfer which means
that we transfer data (some form of state you could say) instead of user interfaces. We just want our server to send us data and we leave it to our client side app be it a mobile application or be it a single page application to do whatever it wants to do with this data. Thus in traditional web applications we rendered the views on the server side using templating engines and handled both the data and the UI . This is not bad at all it is a common pattern for a lot of web applications

Traditional Web Apps and REST APIs - ONLY THE RESPONSE DATA DIFFERS

Often traditional web applications and the REST APIs are seen as totally two different things. They are not, they only differ in the response and the kind of data that you expect but they don't differ at the server besides the fact that you do not render
the view there on the server. Here we use all knowledge that we gathered we only fine tune the data handling and finally deliver it to the client in the format in which it is required by the client.

A MAGNIFIED AND CRYSTAL CLEAR PICTURE OF THE REST APIs

So consider this scenario where we have our client (a mobile app, SPA) and then we have our server on which we build our backend REST API.

Now one possible advantage of this can be that we can make one and the same API for handling multiple clients and this is possible because both our mobile apps and web apps rely on the same data source, right. In fact, both the apps are same and consume the same data source. The only difference could be on how they present this data in their user interfaces.

Contrary to this, we can also have kind of a traditional application which just needs our service APIs. And in all such applications it is the data which is exchanged between the client and the server.

WHAT FORMAT DO WE EXCHANGE THE DATA IN

Some of the common formats that we most likely see are :
1.HTML
2.XML
3.JSON etc.

So there are different kinds of data that we can attach to the request and the response objects. So we can send plain text, XML or we could even send JSON.

There are different kinds of data that we can attach to the
request and the response objects. We can send plain text,XML or we could send JSON.

XML

It looks a lot like HTML. XML allows us to use any tags. It allows us to send any data and does not make assumptions about the user interface because it is not parsable by browsers. They are user defined elements.
These are machine readable but relatively verbose but you can define clear structures here. Here an XML parser is needed because node traversal in XML node tree is kind of a challenge in itself. So in essence you need an XML parser to efficiently parse the XML data.

JSON

JSON is kind of a defacto standard for data interchange in web applications. Here also we work on just the data and the JSON does not make assumptions about the user interface. It is machine readable and a bit more concise than XML and can easily be converted to Javascript.
This is a huge plus when working with Node.js on the server and JavaScript on the browser. It is the most common format used in any of the APIs that you are communicating with these days.

Routing and HTTP methods

Now we know our web works on request and response cycle. So we have a client that interacts with the server in form of requests and response to get the data that it needs and more. Check my video on Client Server Architecture to know more regarding this :

So this is how we communicate with our server. In the REST World, these communications take place in form of paths which are known as API Endpoints

API ENDPOINT = ANY COMBINATION OF THE HTTP METHOD AND THE RESPECTIVE PATH
These are the endpoints that we define on our REST API and we
also define some logic that should get fired when such a request reaches our end point.

HTTP METHODS

More than just GET AND POST(These are only when we are working with links and forms), we have other HTTP methods as well that the browser natively knows of. So here is a short summary of the HTTP methods that our request client has access to.

GET - Get a resource from the server

POST - Post a resource to the server which is responsible for creating or appending a resource to an already existing array of resources so to say.

PUT - Put a resource onto the server(i.e create or overwrite a resource). Post should never overwrite an existing resource though it can do but it is not recommended

PATCH - Update parts of the existing resource on the server(not overwriting the entire resource but the parts of it)

DELETE - Delete a resource on the server

OPTIONS - Determine whether follow up request is allowed(sent automatically by the browser)
This is automatically sent by the browser to find if the next request it tries to do is allowed or not.
It is the best practice to use these methods in this way though you can do anything you want

This way any one who uses your API clearly knows what to expect for a given method

REST PRINCIPLES

1. Uniform interface, clearly defined API endpoints with clearly defined request and response structures
IOW, your API should be predictable and also it should be well documented if it is open to the public.
So people should know what data your API expects and what data it gives back.

2. Stateless interactions
When building the server and the client, the server and the client are totally decoupled and they don't share a common history
,every request is handled separately. And therefore no sessions can be used since no connection history is shared among the client
and the server. Every incoming request is treated as if no prior request was sent. Server has a look on every request on its own. It does not store a session about the client.

You can just build an API and open it to the public and just present the documentation of its usage to the client.
You don't care at all about the clients. You just say here is the endpoints I have ,here is the data you get for each of the well-defined endpoints.
So in essence, we have a strong decoupling between the client and the server even if they were to run on the same server because we are building the API for our application so that they work independently from each other and just exchange data without sharing the connection history.

3.Cacheable

You could send the client some response headers telling the client for how long the response is valid.
Servers may set caching headers to allow the client to cache responses.

4.Client-Server
Client and Server are separated,client is not concerned with persistent data storage.It is the responsibility of the server.

5.Layered System

As a client we send a request to a server, we can't rely on that server we sent it to to immediately handle the request, the server may handle the request to other server or distribute it to other servers if it is busy.
Ultimately we care about the data that we get back which should follow the structure that was defined by the API.

6.Code on Demand

REST API could also for some end points transfer executable code to the client.

So this is it for this article. Thanks for reading.
Don't forget to leave a like if you loved the article. Also share it with your friends and colleagues.

PS - If you are looking to learn Web Development, I have curated a FREE course for you on my YouTube Channel, check the below article :

Looking to learn React.js with one Full Project, check this out :

This content originally appeared on DEV Community and was authored by The Nerdy Dev