Web Development

RESTful API Explained

How do different independent web services built on different platforms on the internet communicate with one another? They do it through many different types of protocols. Today, we will be talking about one of them, RESTful API.

Lim Xing Zhi

16 Aug 2019 — 3 min read

REST stands for Representational State Transfer. It is a design pattern for APIs. A RESTful API is an interface based on that design.

A legal RESTful request will contain the following:

URL
HTTP Method
Headers
Body

In this example, I'm adding a new user at reqres.in using the POST method.

POST /api/user HTTP/1.1
Host: reqres.in
Content-Type: application/json
User-Agent: PostmanRuntime/7.15.0
Accept: */*
Cache-Control: no-cache
Postman-Token: fb5572ee-e4b9-4031-910a-052005e3965d,81dd06fc-3089-40da-a737-e62ebfd95899
Host: reqres.in
cookie: __cfduid=d9e2ca413de05c249fc1c8cadeb24c0651563440726
accept-encoding: gzip, deflate
content-length: 56
Connection: keep-alive
cache-control: no-cache

{
    "name": "john wick",
    "title": "baba jaga"
}

URL

Uniform Resource Locator is literally the URL that you key into your browser. In the example, we used https://reqres.in/api/user. Let's break it down.

Domain - reqres.in
Also known as the host. This points to the webserver that is sitting on reqres.in
URL Path - /api/user
This describes the resource that you want to operate on. /api/user could mean that the resource is a RESTful API and the desired resource is a user. However, this is up to the interpretation of the back end service and could differ among different providers.
URL Parameter - /api/user?usr_id=2
The above example does not have this parameter, but I have included it to illustrate a common structure. The ?usr_id=2 is a simple and readable schema that shows the usr_id parameter has a value of 2.

HTTP Methods

HTTP defines a set of request methods to indicate the desired action to be performed for a given resource - Mozilla Developer Network

HTTP methods are functions that describe the intention to operate on a resource over the internet. For example:

Uploading a new blog post.
Getting the comments of a certain product on a shopping app.
Editing your Reddit comment.
Removing a follower on social media.

These operations are commonly known as CRUD (Create, Read, Update and Delete). But HTTP methods support more than these basic actions.

The common methods include:

POST - Create a new entry
e.g. Creating a new user account
GET - Request data specified
e.g. Return the name of a certain user
PATCH - Modify data
e.g. Make changes to specified data
DELETE - Delete data
e.g. Return the name of a certain user

Many other methods exist, but these are the most commonly used ones.

In the above example, we are using POST. That tells the server that we want to create a new user. However, just like the URL parameter, this is up to the interpretation of the back end server.

The header will provide meta-data about the request. In the above example, we have

Content-Type: application/json - This describes the type of content (JSON text or Image or XML)
User-Agent: PostmanRuntime/7.15.0 - This describes the client (browser or others)

Body

The body will be the data you want to deliver to the service provider.
The body does not necessarily have to contain anything. For example, a GET request is expected to have an empty body, but not a POST.

In the above example, we have a JSON text:

{
    "name": "john wick",
    "title": "baba jaga"
}

Putting it all together

With these 4 components, we can insert a user into the web service.

We look for the domain to issue the request and the resource on the domain - reqres.in and /api/user.
We tell the back end that we are issuing a POST, implying that we want to create a new entry on the user resource.
We describe the type of resource that the body contains.
In the body, we provide the information we want to insert.