Exploring the RESTful Architecture: How the Web Inspired a New Way of Building APIs

REST, which stands for Representational State Transfer, is an architecture that takes inspiration from the World Wide Web. Although REST comprises numerous principles and limitations, we will concentrate on the ones that are most useful in resolving integration difficulties in the context of microservices and when seeking an alternative interface style to RPC for our services.

The most critical aspect of REST is the notion of resources, which can be thought of as entities that the service is aware of, such as a Customer. The server generates various representations of this Customer upon request, and how a resource appears externally is entirely separated from how it is stored internally. For instance, a client may request a JSON representation of a Customer, even if it is stored in an entirely distinct format. Once a client obtains a representation of this Customer, it may issue requests to modify it, and the server may or may not fulfill them.

Rest And HTTP

The REST style integrates very well with the useful capabilities defined in HTTP. For instance, HTTP verbs like GET, POST, and PUT already have defined meanings in the HTTP specification regarding how they interact with resources. According to the REST architecture, methods should behave consistently on all resources, and luckily, HTTP provides a range of methods we can use. Specifically, GET retrieves a resource idempotently, and POST creates a new resource. By utilizing these HTTP methods, we can eliminate the need for numerous createCustomer or editCustomer methods. Instead, we can simply send a POST request with a customer representation to request the server to create a new resource, and use a GET request to obtain a representation of an existing resource. In these scenarios, we have one endpoint in the form of a Customer resource, and the available operations are integrated into the HTTP protocol.

HTTP offers an extensive range of supportive tools and technologies, such as HTTP caching proxies like Varnish and load balancers like mod_proxy. Additionally, many monitoring tools come equipped with pre-built support for HTTP. These building blocks enable us to handle substantial volumes of HTTP traffic and efficiently route them in a transparent manner. With HTTP, we can also leverage all available security controls to secure our communications, from basic authentication to client certificates. However, it is crucial to use HTTP effectively to reap these benefits. If used poorly, it can be just as insecure and difficult to scale as any other technology. But when used correctly, HTTP provides ample assistance to facilitate our work.

Hypermedia As the Engine of Application State(HATEOAS)

Another principle introduced in REST that can help us avoid the coupling between client and server is the concept of hypermedia as the engine of application state. This is fairly dense wording and a fairly interesting concept, so lets break it down a bit.

The concept of hypermedia involves including links to various pieces of content in different formats, such as text, images, and sounds, within a particular content piece. This notion is likely familiar to you, as it mirrors how a typical web page functions: by following links, which are a form of hypermedia controls, to view related content. HATEOAS takes this idea further by suggesting that clients should interact with the server (which may trigger state transitions) through links to other resources. Instead of knowing precisely where customers reside on the server and what URI to target, the client should search for and navigate links to locate the necessary information.

Think of the Amazon.com shopping site. The location of the shopping cart has changed over time. The graphic has changed. The link has changed. But as humans we are smart enough to still see a shopping cart, know what it is, and interact with it. We have an understanding of what a shopping cart means, even if the exact form and underlying control used to represent it has changed. We know that if we want to view the cart, this is the control we want to interact with. This is why web pages can change incrementally over time. As long as these implicit contracts between the cus tomer and the website are still met, changes dont need to be breaking changes.

1.<link rel = /products href=products/item1 />2.<link rel=/instantpurchase href=instantPurchase/1234 />

In this document, we have two hypermedia controls. The client reading such a docu ment needs to know that a control with a relation of products is where it needs to navigate to get information about the product items, and that instantpurchase is part of the protocol used to purchase the album. The client has to understand the semantics of the API in much the same way as a human being needs to understand that on a shopping website the cart is where the items to be purchased will be.

As a client, I do not require knowledge of the specific URI scheme to purchase the album. All I need to do is access the resource, locate the buy control, and proceed to it. The location of the buy control may change, the URI may undergo modification, or the site may redirect me to an entirely different service, but as a client, I need not worry about these details. This setup provides a significant level of decoupling between the client and server.

Data Formats : JSON or XML

Employing standard textual formats offers clients extensive flexibility when consuming resources, and REST over HTTP enables us to use a diverse range of formats. Although the examples I have illustrated until now employed XML, currently JSON has become a more prevalent content type for services that operate via HTTP.

The fact that JSON is a much simpler format means that consumption is also easier. Some proponents also cite its relative compactness when compared to XML as another winning factor, although this isnt often a real-world issue.

Despite its popularity, JSON does come with a few drawbacks. While XML defines the link control as a hypermedia control, there is no equivalent standard in JSON. Therefore, custom in-house styles are often utilized to incorporate this concept. To address this issue, the Hypertext Application Language (HAL) has been developed to establish a common set of standards for hyperlinking in JSON (and XML, though it is arguably less necessary for XML). Adhering to the HAL standard allows for the use of tools like the web-based HAL browser to explore hypermedia controls, simplifying the process of creating a client.

Downsides to REST Over HTTP

One potential downside of using REST over HTTP is performance, which may be a concern for services with low-latency requirements. While REST supports alternative formats like JSON or binary, HTTP still introduces overhead for each request. Additionally, REST payloads may not be as lean as those of binary protocols like Thrift.

Although HTTP is suitable for handling large amounts of traffic, it may not be the best option for low-latency communications when compared to other protocols built on Transmission Control Protocol (TCP) or other networking technologies. One such example is WebSockets, which, despite its name, is not necessarily tied to the Web. Once the initial HTTP handshake is completed, WebSockets operate solely as a TCP connection between the client and server, making it a much more efficient way to stream data to a browser. However, it's important to note that using WebSockets doesn't involve much of HTTP or REST.

For server-to-server communications, if extremely low latency or small message size is important, HTTP communications in general may not be a good idea. You may need to pick different underlying protocols, like User Datagram Protocol (UDP), to achieve the performance you want, and many RPC frameworks will quite happily run on top of networking protocols other than TCP.

Subscribe to newsletter for more :
https://architechinsider.substack.com/