RESTful API 101

Credit: Seobility’s REST API wiki page

When I first learned RESTful API, I pretty much followed every tutorial I can find on how to use RESTful API and then I implemented on my projects. Well, guess what? Before writing this article, I still couldn’t properly form in words when people asked me what RESTful API was. Therefore, I would like to write an article about RESTful API or REST for those who just started to learn about fetching APIs or need a refresher!

Introduction

Let’s say you are searching for “How to use RESTful API” on Google search field, and then hit enter. You will see a list of results, including YouTube videos and articles like what I had below. A REST API works in a similar way, except you get a list of results from the service you are requesting from.

REST stands for REpresentational State Transfer. REST is a software architectural style (or software design pattern) that was created to guide the design and development of the architecture of World Wide Web. REST was first represented by Roy Fielding in 2000 in his Phd dissertation. REST uses various representation to represent a resource, like JSON (for JavaScript developers especially), XML and text, which JSON is the most popular one.

API, which stands for application programming interface, is created by developer to allow the client to talk to the server.

REST determines how the API looks like. It is a set of rules that developer follows when creating the APIs. One of the rules is you should be able to get a piece of data (a.k.a. a resource) when you link to a specific URL.

For those who have used REST in their projects before, you might be familiar with the following four HTTP methods, which are commonly used in REST based architecture:

• GET (Provide a read-only access to a resource)
• POST (Create a new resource)
• PUT (Update a existing resource)
• PATCH (Update a existing resource)
• DELETE (Remove a resource)

Each URL is called a request and the data that got sent back to you is called a response.

RESTful Web Services

When you are looking for resources on how to use RESTful API, you might come across with the term “RESTful Web Services”. A web service is a collection of open protocols (not owned by any particular company and not limited to a particular company’s products — from Khan Academy)and standards used for exchanging data between applications or systems.

A web service that is based on the REST Architecture is known as RESTful web services. You might be familiar with using HTTP methods to create a request for API. These web services uses the HTTP methods that are mentioned above to implement the REST architecture. A RESTful web services usually defines a URI (Uniform Resource Identifier), which provides resource representation such as JSON and a set of HTTP methods.

Let’s say we have the following JSON file which contains multiple users:

{
  "user1": { 
     "id": 1,
     "username": "nerdthegeek",
     "password": "nerd1234"
  },
  "user2": {
     "id": 2,
     "username": "githublover",
     "password": "dontlovegit"
  },
  "user3": {
     "id": 3,
     "username": "theonewhocodes",
     "password": "code2244"
  }
}

With the information above, we are going to provide the following RESTful APIs.

+------------+-----------------+---------------------------------+
|   URI      |   HTTP Method   |            Result               |
+------------+-----------------+---------------------------------+
| listUsers  | GET             | Show list of all the users      |
| addUser    | POST            | Add details of new user         |
| deleteUser | DELETE          | Delete an existing user         |
| :id        | GET             | Shows of that user with that id |
+------------+-----------------+---------------------------------+

It is important to first understand the anatomy of a request before copying any code example from any tutorial (I made that Rookie mistake 🥲).

The Anatomy of a Request

There are 4 things in the request:

1. The endpoint
2. The (HTTP) method
3. The headers
4. The data/body

Endpoint

The endpoint is the URL you request for. The root-endpoint is the starting point of the API you are requesting from. For instance, the root-endpoint of Github API is https://api.github.com . The path determines the resources you are requesting for. You may have seen :username something like that. Any colons (: ) on a path denotes a variable, so you have to replace these values with actual values of when you send a request. So let’s say you would like to access your own Github repo, in my case, it would be:

https://api.github.com/users/mehmehmehlol/repos

(All example reference is based on this article: Understanding And Using REST APIs)

Method

As we mentioned about the HTTP request earlier (GET, POST, PUT, PATCH, DELETE), these methods provide meaning for the requests you are making. You may be familiar with CRUD, which is Create, Read, Update, Delete. The methods are used to perform these four possible actions.

Let’s break these methods down:

• GET : If you perform a GET request, the server looks for the data you requested and sends it back to you. A GET request performs the READ operation. It is also a default request method.
• POST : If you perform a POST request, the server creates a new entry in the database and will tell you whether the creation is successful. A POST request performs the CREATE operation.
• PUT & PATCH : If you perform a PUT or PATCH request, the server updates an entry in the database and will tell you whether the update is successful. A PUT or PATCH request performs the UPDATE operation.
• DELETE : If you perform a DELETE request, the server deletes an entry in the database and tells you whether the deletion is successful. A DELETE request performs a DELETE operation.

(I will update this article with code examples)

Headers

Headers are used to provide information to both the client and the server. it provides additional information with the HTTP request or response. There are many types of headers. The full list is provided in MDN’s HTTP headers. Examples like 'Content-Type': 'application/json' . HTTP headers are always key-value pair. This example tells the server to expect JSON content.

Data/Body

The data contains information you want to be sent to the server. This option is only used with POST , PUT, PATCH or DELETE requests.

There you go! That’s pretty much all you need to know about RESTful APIs! Please let me know what you like to know more about RESTful APIs and what you would like me to add in this article so that it can be more informative and easier to follow, especially for beginners!

Resources

Node.js - RESTful API

REST API Tutorial

Representational state transfer - Wikipedia

Understanding And Using REST APIs - Smashing Magazine