Understanding REST APIs: A Beginner’s Guide

What is an API?

Imagine you are in a restaurant. You do not go to the kitchen and tell the chef what you want to eat. Instead, a waiter comes and takes your order, gives the chef your order, and once it is ready, the waiter brings the food to your table. In this situation, the waiter is the API. The waiter is the intermediary in this situation. He takes your order in a language you understand (e.g., English) and translates it into a language the chef will understand (e.g., kitchen jargon). Similarly, an API takes a request in a language that one program understands (e.g., HTTP) and translates it into a language that another program can understand (e.g., JSON). An API, in full, is an Application Programming Interface. Basically, an API is a way in which two programs can communicate.

What is a REST API?

A REST API is short for REPRESENTATIONAL STATE TRANSFER APPLICATION PROGRAMMING INTERFACE. A REST API is a web API that uses HTTP responses to retrieve and manipulate data. It is based on the principle of REST, which is a set of guidelines that make web apps scalable, flexible, and easy to maintain.

What is The Principles of REST?

REST is based on the idea that every resource on the web should be uniquely identifiable using a URI (Uniform Resource Identifier). This basically means that every piece of data on the web (e.g. pictures, a blog, a user profile) should have its own unique identifier that can be used to access it. It also emphasizes the use of HTTP request methods (which we will discuss later) to manipulate its resources.

Some other emphasis includes:

· Statelessness: This means that the client and server are separate, meaning there is no state.

· Client-server architecture: meaning there is no third party.

· Cacheability: This means that the response can be cacheable (cache is a temporary storage area for frequently accessed web resources. So being cacheable just means it can be stored in a cache)

· Layering: can have multiple intermediaries between clients and servers

· Uniform Interface: meaning it should follow a common protocol.

What is HTTP?

HTTP, in full, is Hypertext Transfer Protocol. This is a set of rules that web browsers and web servers use to communicate over the internet. This is basically a language computers use to talk to each other. When you type in an address in your web browser, it sends an HTTP request to the website’s server. The server then sends an HTTP response to which the browser uses to display the website on your screen.

HTTP is very important. It allows us to access all kinds of information on the internet, from texts to images to video to music. Without it, we wouldn’t be able to browse the web or even use online services like e-commerce.

HTTP Request and HTTP Response

Say, for example, you want to borrow a book from the library. You take the book to the librarian and your school ID and request to borrow the book. In our case, the process of requesting if you can borrow the book is an HTTP request. The librarian will then respond to you with a message whether you are allowed to borrow or not. That message is now the HTTP response. When you type in a web address, let’s say www.medium.com, the web browser sends a message (HTTP request) to the website’s computer that you want access to a certain page on their website. The website computer now sends a message (HTTP response) back to the web browser with what you want.

HTTP request usually has three parts:

1. Request method: This is a verb, e.g. POST, GET, PUT, DELETE, that tells the webserver what you want. (Don’t worry, I will get into more details about this.)

2. URL: This is the address for the resource you want to retrieve or interact with, e.g. www.medium.com, you want the home page.

3. Header: This is additional information about the request.(we will get into more details later on)

HTTP responses also have three parts:

1. HTTP Status Codes. This is like a secret message that is mostly numbers that tells you if everything went OK or if there was an error. This is like the librarian accepting or declining your request to borrow a book.

2. HTTP header. This is like a little note that gives the web browser information about what it is getting. Maybe the message has videos or images.

3. Response body. This is the main part, which is the answer to the question or the thing you asked for.

HTTP request methods.

Earlier, I mentioned that an HTTP request is when you use the internet to visit a website, and the web browser sends a request to the web server asking for a particular webpage or resource. I had also mentioned that the HTTP request has three parts: request methods, URL, and header. Now, I want to dive deep into request methods. Request methods are basically verbs that tell the webserver what you want.

We will use the restaurant analogy again here. Assume you want to order a burger in a restaurant. There are different ways you could order it. You could say, ‘I want a burger’ or you could say, ‘Excuse me, could I please order a burger’ or you could say, ‘Can I please get a burger’. Similarly, when you use a computer or even your phone, and you want to get something from a website or a server, there are different request methods to ask for it.

Here are some of the most common request methods:

1. POST — This is like saying, ‘Hey, here is some information I would like to send to the server’. This method is used to submit information to the server. Note that with this method, it often changes the state of the server.

2. GET — This is like saying, ‘Can I please have this website’. This method is used to fetch the desired resources from the web server.

3. PUT — This is like saying, ‘I want to update this information on the server’. This method is used whenever you want to change a resource that is already part of the resource collection.

4. DELETE — This is like saying, ‘Hey, I want to delete this information from the server.’ This method requests the origin server to delete the resource identified by the request-URL.

5. PATCH — This is like saying, ‘Hey, I want you to go to this specific information and only change this part.’ This method is used to modify only the necessary part of the data or a response. It does not modify the entire response.

HTTP Headers

HTTP headers are special instructions sent to the web server that provide extra information alongside the request. Think of it like adding your address and name at the top of a letter — in the same way, some special information is included at the top of your request, which is now the HTTP header.

HTTP headers may include things like the type of browser you are using (e.g. Chrome, Firefox), the version of your browser, the operating system running on your computer, the language you prefer, and any cookies stored on your computer. This information helps the server provide the best possible experience on the website. For example, if you are using a mobile phone, the server may serve you a mobile-friendly version of the website. So, the HTTP header is like a way for a computer to tell the web server about itself and what it needs from it.

The HTTP header is made up of four main parts:

1. Request header: This is a header that is sent from the client to the server.

2. Response header: This is header sent from the server to the client.

3. Representation header: This contains information about the body of the response.

4. Payload header: This contains information about the payload data (the content being transmitted between the client and server in a web communication).

HTTP Status Code

HTTP status codes are little messages the server sends to the web browser to inform it if the process was successful or not.

Below is sheet containing the http status codes: