REST: A Quick Guide to Building Scalable and Flexible Systems Using HTTP

REST (Representational State Transfer) is an architectural style for building distributed hypermedia systems, such as the World Wide Web. It provides a set of principles for processing and transferring resource states over HTTP. A system that follows the REST principles is called a RESTful system. In this article, we will discuss the characteristics of a RESTful system, including client-server, stateless, cacheable, uniform interface, layered system, and code-on-demand. We will also cover the HTTP methods used to interact with resources, and HTTP status codes that indicate the status of a client's request. By following REST principles, you can create scalable and flexible systems that can be easily maintained and updated.

What is RESTful

For a distributed system to be considered built according to the REST (Restful) architecture, it must meet the following criteria:

1. Client-Server. The system must be divided into clients and servers. Separation of interfaces means, for example, that clients are not tied to data storage, which remains within each server, so client code mobility is improved. Servers are not tied to the user interface or state, so servers can be simpler and more scalable. Servers and clients can be replaced and developed independently as long as the interface does not change.
2. Stateless. The server should not store any information about clients. The request should contain all the necessary information for processing the request and, if necessary, identifying the client.
3. Cache. Each response must be marked as cacheable or not to prevent clients from reusing outdated or incorrect data in response to subsequent requests.
4. Uniform Interface. A single interface defines the interface between clients and servers, simplifying and separating the architecture and allowing each part to evolve independently. The four principles of a uniform interface: 1. Identification of resources. In REST, a resource is anything that can be named, such as a user, an image, an item (a shirt, a hungry dog, current weather), etc. Each REST resource must be identified by a stable identifier that does not change when the resource state changes. The URI is the REST identifier. 2. Manipulation of resources through representations. REST representations are used to perform actions on resources. The representation of a resource is its current or desired state. For example, if the resource is a user, the representation may be an XML or HTML description of that user. 3. Self-descriptive messages. A self-descriptive message contains all the necessary information for processing requests and responses, without the need for additional messages or cache processing a single request. That is, there is no state that is stored between requests to resources, which is critical for scaling the system. 4. HATEOAS (Hypermedia as the engine of application state). The status of a resource is transmitted through the content of the body, query string parameters, request headers, and request URI (the name of the resource). This is called hypermedia (or hyperlinks with hypertext). HATEOAS also means that, if necessary, links can be held in the response body (or headers) to support URIs to retrieve the object itself, or the requested objects.
5. Layered System. REST allows the system to be divided into a hierarchy of layers, but with the condition that each component can only see components of the next layer. For example, if you call the PayPal service, and it in turn calls the Visa service, you should not know anything about the Visa service call.
6. Code-On-Demand (optional). In REST, loading and executing code or programs on the client side is allowed. Servers can temporarily extend or customize client functionality by passing it logic that it can execute. For example, these can be compiled Java applets or client scripts in JavaScript.

HTTP Methods

GET - The GET method retrieves ("reads") a representation of a resource. If the request is successful, GET returns the resource's representation in either XML or JSON format, alongside an HTTP 200 (OK) status code. If there are any errors, it typically returns a 404 (NOT FOUND) or 400 (BAD REQUEST) status code.

Here's a simple Python example of using the requests library to make a GET request:

POST - The POST method is used to create new resources, including nested resources. When a resource is successfully created, a 201 (CREATED) code is returned, and the address of the created resource is passed in the Location header.

Here is a simple Python example of using the requests library to make a POST request:

PUT - The PUT method is typically used to update a resource. When sending a PUT request to an existing resource, the request body should contain the updated data of the original resource (either completely or only the updated part). If the update is successful, a status code 200 (OK) is returned (or 204 (NO CONTENT) if no content was passed in the response body).

Here's a simple Python example of using the requests library to make a PUT request:

PATCH - The PATCH method is used to update part of an existing resource. When sending a PATCH request to an existing resource, the request body should contain the updated data of the original resource (either completely or only the updated part). If the update is successful, a status code 200 (OK) is returned (or 204 (NO CONTENT) if no content was passed in the response body).

Here's a simple Python example of using the requests library to make a PATCH request:

DELETE - The DELETE method is used to delete a resource identified by a specific URI (ID). Upon successful deletion, it returns code 200 (OK), along with the response body containing data of the remote resource.

Here's a simple Python example of using the requests library to make a DELETE request:

HTTP Status Codes

HTTP status codes are standard response codes that indicate the status of a client's request. Below are some of the most commonly used codes:

1XX: Information

100: Continue - This code indicates that the server has received the initial part of the request and that the client should proceed to send the remaining part of the request.

2XX: Success

200: OK - This code indicates that the request was successful and that the server has returned the requested data.

201: Created - This code indicates that a new resource has been successfully created based on the client's request.

202: Accepted - This code indicates that the server has received the request but has not yet completed processing it.

204: No Content - This code indicates that the request was successful but that there is no content to return.

3XX: Redirect

301: Moved Permanently - This code indicates that the requested resource has been permanently moved to a new URL.

307: Temporary Redirect - This code indicates that the requested resource is temporarily available at a different URL.

4XX: Client Error

400: Bad Request - This code indicates that the server is unable to understand the client's request due to a malformed syntax.

401: Unauthorized - This code indicates that the client needs to authenticate in order to access the requested resource.

403: Forbidden - This code indicates that the client does not have access to the requested resource.

404: Not Found - This code indicates that the requested resource could not be found on the server.

5XX: Server Error

500: Internal Server Error - This code indicates that the server encountered an error while processing the request and was unable to complete it.

501: Not Implemented - This code indicates that the server does not support the requested functionality.

502: Bad Gateway - This code indicates that the server received an invalid response from the upstream server while acting as a gateway or proxy.

503: Service Unavailable - This code indicates that the server is currently unavailable and cannot handle the request.

504: Gateway Timeout - This code indicates that the server received a response from the upstream server that took too long to complete.

Conclusion

In conclusion, REST is an architectural style for building distributed hypermedia systems that includes universal methods for processing and transferring resource states over HTTP. A RESTful system must be client-server, stateless, cacheable, have a uniform interface, a layered system, and allow code-on-demand. HTTP methods such as GET, POST, PUT, PATCH, and DELETE are used to interact with resources, and HTTP status codes indicate the status of the client's request. By following REST principles, you can create scalable and flexible systems that can be easily maintained and updated.

Thanks for reading and happy creating!

I hope this article has been helpful for you. Thank you for taking the time to read it.

To keep the inspiration flowing, check out my other articles. Let's continue to learn and grow together!