software development

How Do Rest APIs Work

REST or RESTful APIs are everywhere these days. You may have used it even without knowing anything about it.  In this article, I will talk about REST APIs. I will discuss how they work, their applications and many more. Let’s get started.

Why USE REST API:

In traditional web applications, let’s say a simple PHP web server,

  • You request a page (let’s say php) from the server.
  • The server finds the script file (php) corresponding the page you requested and starts executing it. The script connects to the database, looks for the required information, places the information into the page in a nicely formatted way (mixing HTML + CSS + JavaScript with the data) that looks very attractive to the visitor.
  • Then the server sends it back to the visitor.

In this model, all the processing is done on the server side. So the server has to do more work. Here, data is not separate from the page, it’s embedded deeply into the page.

If in future, you want to make an Android app or iOS app or a Desktop app of your website, you will have to do a lot more work. You will have to connect to the database directly from each of these apps, which may not be very secure. The development time will increase and portability issues will arise.

Let’s say you’ve successfully made Desktop, Android and iOS apps of your website. The user’s full name is displayed in lowercase in each of them. Now, you would like to show it in uppercase. Well, the developers have to modify the Desktop, Android and iOS version of your app separately in order to do that. Which is time consuming. In real world, things won’t be as simple as this one. So, one version of the app (Let’s say the Desktop version) may have a serious bug in the update process. Fixing it later would take more time. Can you see how the development time increases? This solution is not portable as well.

In REST API, you ask the API server what you need and it sends you just the information you ask for, no additional formatting is done in the server. There is no need for unnecessary processing in the server. So, the performance of your website and apps are naturally improved. Also, you can use the same data in your website, desktop app, Android and iOS apps. Changes made to the servers will be reflected in the apps that are using the API. The app development time and cost will also be reduced.

How REST API Work:

The REST APIs have endpoints. An endpoint is nothing more than a URL, but in a nicely formatted way and it is meaningful. It uses the native HTTP requests (such as GET, POST, PUT, DELETE etc) to decide what to do when you access each endpoints. I will talk about these later.

The output format of the REST API is JSON also known as JavaScript Object Notation.

An example of the output of a GET request to the REST API on /users/id/12 endpoint may look as follows:

{
  "id": 12,
  "name": "David Smith",
  "age": 42,
  "phones": ["124-211-2341", "889-211-4545"],
  "country": "US"
}

As you can see, I did a GET request on /users/id/12 endpoint to tell the REST API to give me information about the user who has the id 12. I got just the information I requested, nothing more, nothing less.

Now let’s say, you want information on the last 10 users who signed up on your website. You may do a GET request on /users/latest/10 endpoint.

You can add new data on your server using the REST API as well. Usually, the HTTP POST request is used to ask the REST API to add new data to the API server.

For example, you can do a POST request on /users endpoint with the data of the new user and it will be added to the database on your API server. You can also configure your API to return the status of the request.

{
  "statusCode": 400,
  "statusText": "User successfully added.",
  "data": {
  "id": 13,
  "name": "Mary Smith",
  "age": 35,
  "phones": ["124-211-2341", "889-211-4545"],
  "country": "US"
          }
}

As you can see, the statusCode and statusText property of the JSON object notifies the API client that the user is successfully added. The data added is returned as well in the data property of the JSON object. You can configure your API just the way you want.

You can update an existing record from the API server’s database as well. The PUT HTTP request is used on an API endpoint to update existing data on your API server’s database.

For example, let’s say you want to update the phone number of the user with the id 13. You may do a PUT request on the API endpoint /user/id/13.

{
  "statusCode": 200,
  "statusText": "User updated.",
  "old_data": {
  "id": 13,
  "name": "Mary Smith",
  "age": 35,
  "phones": ["124-211-2341", "889-211-4545"],
  "country": "US"
              },
  "new_data": {
               "id": 13,
               "name": "Mary Smith",
               "age": 35,
               "phones": ["100-211-1111", "140-211-1145"],
               "country": "US"
}
}

As you can see, the update operation is successful. The old data and new data is returned in the old_data and new_data property of the JSON object respectively.

You can also delete data from the API server’s database with the HTTP DELETE request on the API endpoint.

For example, to delete the user with the id 12, you may do a DELETE request on the API endpoint /user/id/12.

{
"statusCode": 150,
"statusText": "User removed.",
"data": {
        "id": 12,
        "name": "David Smith",
        "age": 42,
        "phones": ["124-211-2341", "889-211-4545"],
        "country": "US"
        }
}

As you can see, the user is deleted and the deleted user data is returned in the data property of the JSON object.

I have explained the standard way to use the GET, POST, PUT and DELETE HTTP request on the API endpoints to do CRUD (Create, Read, Update and Delete) operation using REST API. But you can configure your API to do certain things on certain HTTP request. Nothing is fixed here. For example, you can update the API using GET HTTP request. You don’t have to use PUT. It’s up to the API designer.

You design the API endpoints as well. Giving meaningful names to your API endpoints make your REST API much easier to use.

Applications of REST API:

APIs make app development easier and modular. With the help of REST API, you can easily port your app to different platforms.

All you have to do is design and develop a REST API of your application. Then you can use your REST API from your website, Android app, iOS app, Windows desktop app and Linux app etc. This way, all of your apps on different platform will use the same logic and your development time and cost will be reduced. The apps will be easier to manage as well. REST APIs are used rapidly in Single Page Web Applications these days as well.

I have written an article on writing REST APIs using Python.  Thanks for reading this article.

About the author

Shahriar Shovon

Freelancer & Linux System Administrator. Also loves Web API development with Node.js and JavaScript. I was born in Bangladesh. I am currently studying Electronics and Communication Engineering at Khulna University of Engineering & Technology (KUET), one of the demanding public engineering universities of Bangladesh.