RESTful API Services - The Basics

Most of you, especially those who have a keen interest in web development, have come across the term "REST API".
Overall it serves the purpose of fetching data from a source on the internet and we use that data in building our own applications. But there is certainly more to that.

In this article, I will try to cover some of the basics of REST APIS, like what is a REST API and why it is called so, formats in which data transfer happens, and in the end, we will do an anatomy of a full REST API Request.

So, let's get started

First and foremost, "What is an API?" 

Well, to put it in simple terms an API (Application Programming Interface) is like a user-interface to raw data and it is for the use of applications rather than for the use of humans. Also, there exists a well-defined agreement between the API producer and consumer, like in which format data will be exchanged between the parties, some authorization tokens/cookies in the request header, etc.

Now REST stands for Representational State Transfer. To understand what do we mean by a representational state, let's touch upon the concepts of entity and attributes of DBMS. An entity, as we know, is a real-world object, and attributes are the properties that define the entity. Like a car is an entity having attributes like manufacturer, color, model no., etc as it's attributes. In other words this model no., manufacturer, color, etc. uniquely represents a car, so we say all these attributes together form the representational state of the car. 

Have a look at this image below:

Here, we have an entity Book. Its attributes are ISBN, title, edition, category, and author. So together these attributes form the representational state of each book. Now suppose we have an API in which we request with an ISBN and get back the details of the book, i.e. the current representational state of the book. What the API does here it takes the ISBN, queries the database with that ISBN and returns the representational state of the book that matches the ISBN. So, the API is a REST API as it transfers the representational state of the book from the database to the client.

Another aspect here is about the format of the data being transferred through a REST API. Well, REST API doesn't have any standard data format. A REST API is supposed to accept data in any format and send back the response in any format. Generally, a REST API has two parts to it, one it queries the database and gets the data row(s), and then there is a logical part that forms the response data in a specific format like JSON, XML or Text format. 

Now let's look at an actual REST API

GET https://maps.googleapis.com/maps/api/place/textsearch/json?query=restaurants+in+Sydney&key=AB123z

This is an API provided by Google Maps Platform. Here 'GET' represents the HTTP Method. There are no. of HTTP Request Methods to indicate the desired action. We can learn more about HTTP Request Methods here. 
The anatomy of the API is as follows:

• Root Endpoint: Here https://maps.googleapis.com/ is the root endpoint. For a particular API provider, the root endpoint is the same.
• Path: After the root endpoint, maps/api/place/textsearch/json part is the API path. The path will be different for different APIs by a particular provider. One thing to note here is the /json is a path variable. In this API, this particular variable denotes the data format in which the response will be returned. We can put /xml here to get the response back in XML format.
• Parameters: The part query=restaurants+in+Sydney&key=AB123z are the query parameters. These are in key-value pairs. Apart from query parameters, there can be body parameters that are sent in the request body.

One thing to remember about REST API is:

REST is not any standard or technology rather it is an architectural style for developing API based on a standard set of principles.

These things will help us to get a basic understanding of REST APIs. Although, there are many other things related to it, like architectural constraints, API security, and API Management. In the next article, I will be sharing REST API principles and architectural constraints, so do subscribe. Till then, Stay Safe and Happy Coding!