RESTful API 101
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!
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.
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:
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:
- The endpoint
- The (HTTP) method
- The headers
- The data/body
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:
(All example reference is based on this article: Understanding And Using REST APIs)
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
GETrequest, the server looks for the data you requested and sends it back to you. A
GETrequest performs the
READoperation. It is also a default request method.
POST: If you perform a
POSTrequest, the server creates a new entry in the database and will tell you whether the creation is successful. A
POSTrequest performs the
PATCH: If you perform a
PATCHrequest, the server updates an entry in the database and will tell you whether the update is successful. A
PATCHrequest performs the
DELETE: If you perform a
DELETErequest, the server deletes an entry in the database and tells you whether the deletion is successful. A
DELETErequest performs a
(I will update this article with code examples)
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.
The data contains information you want to be sent to the server. This option is only used with
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!
Node.js - RESTful API
REST stands for REpresentational State Transfer. REST is web standards based architecture and uses HTTP Protocol. It…
REST API Tutorial
REST is acronym for REpresentational State Transfer. It is architectural style for distributed hypermedia systems and…
Representational state transfer - Wikipedia
Representational state transfer ( REST) is a software architectural style that was created to guide the design and…