Blog postWhat is REST API?

What is REST API? in plain English

Published July 31, 2018

You're using REST API too long but are not sure what that means? Want to develop applications but the basic terms sound confusing? In this tutorial you'll learn the basics of REST API. Easy, simple and in plain English.

In this tutorial we'll learn:

  1. What is REST, API and REST API?
  2. The HTTP protocol
  3. The requests are sent to URLs
  4. The 2 parts of the returned response
  5. The HTTP status code
  6. Conclusion

# What is REST, API and REST API?

API (Application Program Interface) is an agreed way to send and receive data between computers. For example, if you want to display Google Maps on your site, but the maps are on Google's servers, you need a way to ask Google to provide you with the maps. The way to ask Google to send you the requested maps is through an API provided by Google that tells you to which web addresses should you send the requests to get the data. In a more formal language, you need to send a request to the remote server to get a response.

REST (Representational State Transfer) is an API that defines a set of functions that programmers can use to send requests and receive responses using the HTTP protocol methods such as GET and POST.

REST API can be used by any site or application no matter what language it is written in because the requests are based on the universal HTTP protocol, and the information is usually returned in the JSON format that almost all of the programming languages can read.

How does REST API work?

# The HTTP protocol

If you ever used the internet you sure have a sense of how it works. It sends requests from your personal computer and receives back data from remote servers. That's the internet in a nutshell. And it is feasible because all the computers that use the net speak in the same language, the same protocol with the name of HTTP.

HTTP is the protocol on which the internet is based. It allows computers from anywhere in the world to send requests to remote servers, and get back responses that can be displayed in browsers.

For example, to create a new article on our blog, we should send a request to a remote server using the POST HTTP method. To view a single article or a list of articles, we use the GET method. The PUT method can be used to edit an existing article, and the DELETE method to delete.

The following table summarizes the 4 most useful HTTP protocol methods:


Retrieves data from a remote server. It can be a single resource or a list of resources.


Creates a new resource on the remote server. *


Updates the data on the remote server.


Deletes data from the remote server.

* Some APIs use the POST method to perform any change to the database. Creating, updating or deleting.


# The requests are sent to URLs

The requests should be sent to URLs on the remote server. For example:

To view the list of articles a GET request is sent to the URI:

If we want to view an article with the id of 1, we send a GET request to the URI:

To create a new article, we send the data with the POST method to:

* This is not a mistake. The URI is the same one used to bring the list of articles. But the result is different because here we use the POST method.

To edit the article with the id of 1 we prefer to use the PUT method, and send the request to:

To delete an article we use the DELETE method. We also need to specify the id:

# The 2 parts of the returned response

The data that the server returns contains 2 parts:

The response body is also known as the payload. It is usually formatted in JSON. It contains the data that we want to show to the users. For example, the list of articles or an individual article. The response body is not necessary. For example, when you delete an article, there is no point in returning the data that is no longer stored on the remote server.

The second part is the head that includes the metadata for the request, such as the URL and the IP address, response time, and much more.

# The HTTP status code

Maybe the most important metadata which is sent in the head of the response is the HTTP status code. For example, a 404 code to indicate that the resource does not exist, and a 200 code to state that the resource exists and that the requested data is returned in the response body.

The status codes can be divided into these groups:

The class of 2XX (200, 201, 204) indicates that the data was received and the operation was performed.

The class of 3XX (301, 302) redirects the request to another URL.

The class of 4XX (403, 404) indicates that the resource was is not found or not available to the client.

The class of 5XX (500) to indicate a server error.

The following table summarizes the 10 most common response codes that every developer should know:

Code Message Description
200 OK The data was received and the operation was performed.
201 Created The data was received and a new resource was created. The response needs to return the data in the payload.
204 No content The operation was successful but no data is returned in the response body. This is useful when deleting a resource.
301 Moved permanently This and all the future requests should be redirected to a new URL.
302 Moved temporarily The resource moved temporarily to another URL.
400 Bad request The server cannot accept the request because something is wrong with the client or the request that it sent.
403 Forbidden The client is not allowed to use the resource.
404 Not found The computer is not able to find the resource.
405 Method not allowed For example, when sending a DELETE request to a server that doesn't support the method.
500 Internal server error Service unavailable due to error on the server side.

To see the complete list of status codes go to Github.

# Conclusion

In this tutorial you learned the basics of REST API and now you are ready to code your own application which is based on the REST architecture.

In the following tutorials you will learn to develop an Angular and PHP app which is based on the principles of the REST API.

comments powered by Disqus