HTTP and REST APIs

HTTP is the most popular application protocol on the internet, which allows transfer of data between machines and makes actions like visiting web pages happen.

When we enter a website URL, the browser creates a HTTP Request on our behalf and sends it to the server on which the website is hosted.

The server machine receives the request, understands it and takes appropriate action. The response again has to be formatted in a specific manner adhering to the HTTP protocol for the client to make sense of it.

And depending upon whether it’s a success, sends a HTML document along with the other resources like images, CSS & JavaScript which is read by the browser and rendered beautifully as web pages.

To better understand how a request message looks like, press Ctrl+Shift+I . This will open the Developer tools on your screen. Now, click on Network tab if it isn’t already open and reload the page. When it’s done reloading, click on any of the item in the list and it will open the Headers tab.

For better understanding, I’m attaching an image for reference below.

Now, two important thing to understand here is about Request Method and Status Code.

HTTP Request Methods

HTTP protocol defines a set of request methods. A client can use one of these request methods to send a request message to an HTTP server. The methods are:

• GET: A client can use the GET request to get a web resource from the server.
• HEAD: A client can use the HEAD request to get the header that a GET request would have obtained. Since the header contains the last-modified date of the data, this can be used to check against the local cache copy.
• POST: Used to post data up to the web server.
• PUT: Used to already update an already existing data.
• DELETE: Ask the server to delete the data.
• TRACE: Ask the server to return a diagnostic trace of the actions it takes.
• OPTIONS: Ask the server to return the list of request methods it supports.
• CONNECT: Used to tell a proxy to make a connection to another host and simply reply the content, without attempting to parse or cache it. This is often used to make SSL connection through the proxy.
• Other extension methods.

HTTP Status Codes

HTTP Status codes are part of the HTTP Response. It helps the client understand what happened to the request. Status codes are 3 digit numbers (201, 304, etc.) and are categorized to 5 different families based on their starting digit. Along with the status code, a Reason-Phrase is also present (OK, Moved Permanently etc.) which gives a short description of the status code. The Status Code is intended for machines whereas Reason-Phrase is for humans.

• 1xx — Informational responses
• 2xx — Successful responses eg: 200 OK — Request successfully completed
• 3xx — Redirects eg: 301 Moved Permanently — Requested resource was moved permanently to a different location
• 4xx — Client errors eg: 404 Not Found — Requested resources wasn’t found
• 5xx — Server errors

That’s it, now you know the basics of HTTP. Here are the important parts:

• HTTP is a text based protocol
• It is made up of requests and responses
• Its’ responses have a status code

REST APIs

APIs (Application Program Interface) are how different software programs communicate with each other. Application developers specify the rules of “How to communicate” with their application, these are APIs.

For example, Google Maps API specifies how other applications can use it to provide maps services to their users.

Usually, when we talk about API, we mean REST API.

REST (Representational State Transfer) APIs are those APIs which follow the guidelines set by the REST architecture. They follow a client-server model where one software program sends a request and the other responds with some data. REST APIs commonly use the HTTP protocol to send requests & receive responses.

Here are the some basic design guidelines to make a RESTful API:

1. Resources (URIs) — To describe your resources, use concrete names and not action verbs. The action should be indicated by the HTTP request method that we’re making. e.g. POST: /articles/ may mean "Create a new article".
2. HTTP methods — One should systematically use HTTP verbs to describe what actions are performed on the resources. The most common methods include GET, POST, PUT, and DELETE.
3. HTTP headers — HTTP header fields provide required information about the request or response, or about the object sent in the message body.
4. Query parameters — Make use of the query string for filtering and pagination. e.g. GET: /articles/?page=1&page_size=10
5. Status Codes — It is very important that as a RESTful API, you make use of the proper HTTP Status Codes especially when mocking RESTful API.

JSON is a standard format that is easily “understandable” by applications and can be handled well in most languages. So the data format in REST should usually be JSON. For example, an Android app can effortlessly utilize data sent by a Node.js server. XML is another popular format for data transfer between applications.

How an API request differs from a usual HTTP request for a webpage is in terms of the data returned. HTTP requests for webpages return HTML, CSS & JavaScript files which are rendered by the browser and displayed to the user. But, in the case of APIs, the request can be for any data (not just webpage) and the response is read by the requesting program which interprets the data.

REST architecture and HTTP 1.1 protocol are independent from each other, but the HTTP 1.1 protocol was built to be the ideal protocol to follow the principles and constraints of REST.

One way to look at the relationship between HTTP and REST is, that REST is the design, and HTTP 1.1 is an implementation of that design. In reality the two were designed simultaneously.