What is REST API?

Let’s go through an example to understand what a REST API is. Let’s say that we work for a cloud kitchen and we want to build a web application that can give you how much stock particular items suppose ice cream flavors are available and the worker working on the physical location of the kitchen makes updates to those flavors. So the question arises how do we do this?

The answer will be with a REST API.

Most of the application today uses 3-tier architecture. Some complex systems can even have an n-tier architecture which we called microservices, which will be explained in another post in the future.
So In 3-tier architecture…

• Backend (Application tier)
• Frontend (Presentation tier)
• Database (Data tier)

So we have our frontend app or web page communicate with a cloud-based backend server via a REST API. We use the term REST API whenever our Frontend app communicates with our Backend server. So Let’s jump into what exactly a REST API is.

What does REST stand for?

REST – Representational State Transfer.

This is a type of web communications protocol that allows browsers to access data from a server using the HTTP or HTTPS protocols. RESTful architecture is an approach to designing and building software systems such as websites, mobile applications, and web services that use HTTP methods to manipulate resources residing on the server. RESTful APIs are becoming more popular because they are lightweight, easy to use and consume, and easy to read and understand. They allow for easier integration with front-end developers’ code. A RESTful API can be accessed via different devices such as computers and smartphones by using a library or framework known as a client library.

It’s a standardized software architecture style which is a specific type of API that’s an industry known and used.

The first thing that we have to know about REST API is, that they’re all about communications. So this is how our frontend application communicates with our backend server. Sometimes we also heard RESTFUL Web service, which means is when a service that uses REST APIs to communicate. Let’s go through some of the benefits of REST API

1. Simple/Standardized – approach to communication. We don’t have to worry about how to format our data or how to format each request coming to our system.
2. Scale – As our service grows in complexity, we can make modifications to handle a large number of requests
3. Stateless – we don’t have to worry about what data is in which state they’re in and keep track of that across client and server.
4. High Performance – even though our service gets more complex the performance remains very high.
5. Cache – It supports caching too.

Let’s back to our example again, for the cloud kitchen shop, a REST API would look like the below…

We have an endpoint that might look something like this: https://api.littlegiants.io/v1/items
So api.littlegiants.io is our DNS(Domain Name Server) for our backend application and the api part signifies it’s an API subdomain and v1 means it’s the version one of that API and items represents a resource. So, this signifies that we’re working with the items resource in this REST API.

In our example, we can build some blocks to define REST API.

First, we have to be able to send a request to the server or a specific service in our case cloud kitchen service. So, for a REST API call request we need to have some blocks.

Lets break Request & Response apart a little bit. Let’s say Request as a big black box.
First things first, let’s define the type of things that we might want to do with a REST API. What actions or verbs would we want to use when working with one?
As a developer, we have all heard of CRUD – what does CRUD stands for?

• Create
• Read
• Update
• Delete

So what’ll be the equivalent of Create in an HTTP method? Well, it’s POST. How about Read – it’s GET. An update would be PUT, Also Note if you want a partial update we use PATCH and for DELETE we use DELETE HTTP methods.

The Request itself has some blocks which will be explained below…

1. Operation – This could be HTTP methods like POST, GET, PUT, PATCH, etc. In our case, we’ll use PATCH to update the item stock in our application.
2. Parameters/Body – Although this is Optional. In our case, we send a JSON object as a body stating the current stock of the item in our system.
3. Endpoint – This part will be exposed by the cloud kitchen service where we need to send the resource’s current state to the endpoint. https://api.littlegiants.io/v1/items
4. Headers – This is a special part of a REST API request which might have things like an API key or some authentication data.

The above four points act as a request in a REST API call.

So now the question is what will be the response of the REST API call? Typically it’s some form of raw data, maybe JSON(Which Stands for Javascript Object Notation) or maybe XML(Extended Markup language), etc. In JSON it might look like below

{
    "message": "items updated"
}

Let’s look at a few different scenarios that might happen with our cloud kitchen shop. So let’s say that we want to display what’s products we’re selling in the shop. For that, we have to get the items we have in the shop. From the Request point of view how it looks like?
Well, we have the GET HTTP method as the operation, the endpoint is https://api.littlegiants.io/v1/items, Also parameters can be set to get a single item in the endpoint, headers are some Authorization: Bearer access_token for authenticated endpoints.
In response, we’ll get a list of item resources.

{
    [
        {
            "item_id": 1,
            "name": "Burger",
            "price": 10,
            "stock": 5
        },
        {
            "item_id": 2,
            "name": "Sandwitch",
            "price": 8,
            "stock": 3
        }
    ]
}

So we get some items like burgers, sandwiches, etc. In our shop let’s say a Sandwich is so popular that it runs out for the day and the store is scrambling and they want to update the stock of that item. So let’s say they want to update the Sandwich stock so that they can sell Sandwich.
Well, we have the PUT HTTP method as the operation, the endpoint is https://api.littlegiants.io/v1/items/2, Also parameters 2 represent the Sandwich item in the endpoint also in the body we add the latest stock value as json,

{
    "name": "Sandwitch",
    "price": 8,
    "stock": 10
}

headers are some Authorization: Bearer access_token for authenticated endpoints.

Let’s say we want to add a new item in the store like Ice cream. Well, we have the POST HTTP method as the operation, the endpoint is https://api.littlegiants.io/v1/items, As body, we add the latest item value as json,

{
    "name": "Ice Cream",
    "price": 4,
    "stock": 10
}

headers are some Authorization: Bearer access_token for authenticated endpoints.
In response, we see a response like below

{
    "item_id": 3
    "name": "Ice Cream",
    "price": 4,
    "stock": 10
}

Let’s say some item is not selling at all in the shop so the store owner decided to remove it from the store. Well, we have the DELETE HTTP method as the operation, the endpoint is https://api.littlegiants.io/v1/items/3, Also parameters 3 represent the item in the endpoint, headers are some Authorization: Bearer access_token for authenticated endpoints.

If you like, you can read the same article on my [Personal blog]

You can read my other blog-posts [Here]

In Conclusion, We’re hoping that this clarifies what exactly is a REST API. What are some of the benefits? What’s a real-world example look like and how are the REST APIs fundamental to cloud-based application development?