Understanding HTTP requests and REST APIs

HTTP and REST are shortcuts that are quite popular and widespread. If you touched programming at least for a bit, you, for sure, had the opportunity to hear about these two terms that we'll talk about in this article and I will try to answer every question you might've had about them.

What is HTTP?

Hypertext Transfer Protocol (HTTP) is a protocol for transmitting hypermedia documents, such as HTML. It is designed to enable communication between clients and servers. This protocol is based on a request-response communication between a client and a server.

An example of HTTP usage would be us entering a URL of a website we want to visit  -  where the browser we're using would be the client that's making the request in this communication and the server where the contents of the website are physically located would be the server that gives the response.

HTTP methods

HTTP has multiple defined methods which are indicating the action that we want to perform. The most commonly used HTTP methods are POST, GET, PUT, PATCH, and DELETE.

We choose which method to use depending on the action we'd like to perform, as the names suggest, so we use GET to make a request that will get data from the server, POST to make a request to send data to the server, etc.

Understanding of HTTP Requests and Responses

HTTP Requests

As we said above, HTTP requests are made in order to get a response from a server. These requests are sent in a form of messages that have a predefined format which consists of four parts:

1. Request line  -  consists of the HTTP request method (GET/POST/PUT/PATCH/DELETE), the URI we're calling and the HTTP protocol version;
2. Headers  -  these fields allow the client to pass to the server some additional information about the request and the client itself;
3. An empty line  -  indicating the end of the header fields;
4. Message body (optionally)  -  we usually send a message body in POST requests where we use this section to send the data that needs to be sent to the server.

Here's a simple example of a request that consists of all the parts that are mentioned above:

POST /test HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
Host: www.test.com
Content-Type: text/xml; charset=utf-8
Content-Length: 60
Accept-Language: en-us

name=Test&age=

HTTP Responses

Once the server receives the request, it processes it and returns a response which is also sent in a form of a message with a predefined format which consists of the following parts:

1. Status line  -  consists of the protocol version and a numeric status code followed by its textual interpretation, which tells us more about the way the request was interpreted. There are 5 types of status codes that are distinguished by their first digit, so a response can be 1 - Informational, 2 - Success, 3 - Redirection, 4 - Client error, 5 - Server error;
2. Headers  -  similar to the requests, these fields allow the server to pass to the client some additional information about the response, and about the server itself;
3. An empty line  -  indicating the end of the header fields;
4. Message body (optionally).

Understanding of REST

REST stands for Representational state transfer and it's a software architectural style that uses a subset of HTTP. In other words, it's an architectural style that consists of rules based on HTTP that tell how are our APIs going to be built and what will they look like.

APIs that follow REST rules are called RESTful.

RESTful APIs are characterised to be stateless which means that the server doesn't need to know anything about the state that the client is in and vice versa. Meaning that both the server and the client can understand any message received without the need of seeing previous messages.

REST terminology

• Resources  -  a noun that describes any object, document, or thing that we may need to store or send to other services;
• Resource identifiers  -  these are the URIs (Uniform Resource identifiers) that identify the resource;
• REST verbs  -  with this term we are referring to the HTTP methods;
• CRUD  -  stands for Create, Read, Update, Delete and represents the actions that we can perform to a resource of a RESTful API.

Example

Now let's see what this terminology means in practical terms by diving into an example of a simple RESTful API that implements all CRUD operations.

Let's say that we have an API that provides all CRUD operations for Users and their Tasks.

In this example, we have two types of resources, Users and Tasks. The resource identifiers are shown in the second column of the table above and the REST verbs are in the first one.

REST rules

So, from what we can see in the example above, REST introduces some simple rules, such as:

1. Use JSON
2. Use the plural version of the resource noun in the resource identifiers - As it is in our example, users and tasks;
3. Use nouns instead of verbs in the resource identifiers - As it is in the example, when we want to remove a user we don't define our resource identifier to be /delete-user, instead, we use the HTTP method DELETE as a way to tell the server that we'd like to remove the user and we define the resource identifier with the plural of the resource followed by its ID as a way to refer to the exact item we'd like to remove;
4. Use hyphens (-) to improve the readability of resource identifiers - As we have in our example, user-id, task-id;
5. Use resource nesting to show relations or hierarchy - Resources very often are related to each other, so in order to keep and show their relationships, we should use resource nesting. In the example above, the users and the tasks are related to each other, so we used resource nesting in their resource identifiers definition. This is introduced in the second table of the example above, where we have the operations of the user's tasks. For example, to update a user's task we have this resource identifier: /users/{user-id}/tasks/{task-id} and as we can see we're first finding the user we're targeting and then we're nesting the task with the specific ID whose owner is that user.

Conclusion

Learning about REST and understanding the rules that make it so intuitive was really fun for me. As well as writing this article was super useful and insightful for me.

I hope you feel the same after reading it and I hope I managed to help you understand REST and HTTP better.

Any questions you might have, please let me know! I'm more than happy to help!

Keep coding, do awesome stuff, and stay happy! 😊