Easy Tutorial
❮ Bubble Sort Js Filter Table ❯

RESTful Architecture Explained

Category Programming Technology

1. What is REST

REST stands for Representational State Transfer, which in Chinese means representational state transfer (editor's note: usually translated as representation). It first appeared in Roy Fielding's doctoral dissertation in 2000, and Roy Fielding is one of the main authors of the HTTP specification. He mentioned in his paper: "The purpose of writing this article is to understand and evaluate the architectural design of network-based application software in accordance with architectural principles, and to obtain an architecture that has strong functionality, good performance, and is suitable for communication. REST refers to a set of architectural constraints and principles." If an architecture complies with the constraints and principles of REST, we call it a RESTful architecture.

REST itself did not create new technologies, components, or services. The philosophy behind RESTful is to use the existing features and capabilities of the Web to better use some of the guidelines and constraints in the existing Web standards. Although REST itself is deeply influenced by Web technology, theoretically, the REST architectural style is not bound to HTTP, but currently, HTTP is the only instance related to REST. So the REST we describe here is also the REST implemented through HTTP.

2. Understanding RESTful

To understand the RESTful architecture, it is necessary to understand what the phrase Representational State Transfer means, and what each word implies.

Let's discuss around the principle of REST, focusing on resources, from the perspective of resource definition, acquisition, representation, association, state transition, and list some key concepts and explain them.

2.1 Resources and URIs

What does the full name of REST, Representational State Transfer, refer to? In fact, it refers to resources. Anything that needs to be referenced is a resource. Resources can be entities (such as phone numbers) or just abstract concepts (such as value). Here are some examples of resources:

To make a resource recognizable, it needs a unique identifier, and in the Web, this unique identifier is the URI (Uniform Resource Identifier).

A URI can be seen as both the address and the name of a resource. If some information is not represented by a URI, then it cannot be considered a resource, but only some information about the resource. The design of URIs should follow the principle of addressability, be self-descriptive, and be intuitively associated in form. Here are some good URIs from the GitHub website as an example:

Let's look at some tips for URI design:

Once upon a time, URIs on the Web were cold numbers or meaningless strings, but now more and more websites use _ or - to separate some words, making URIs look more humanized. For example, the well-known open source community in China, its news address on the website uses this style, such as http://www.oschina.net/news/38119/oschina-translate-reward-plan.

For example, the above /git/git/commit/e3af72cdafab5993d18fae056f87e1d675913d08 represents a multi-level resource, referring to a commit record of the git project of the git user, and /orders/2012/10 can be used to represent the order records of October 2012.

Many people simply regard ? as the transmission of parameters, which can easily make the URI too complex and difficult to understand. The ? can be used to filter resources, for example, /git/git/pulls represents all the push requests of the git project, and /pulls?state=closed represents the closed push requests in the git project, and this URL usually corresponds to some specific query results or algorithmic results.

Sometimes when we need to represent the relationship between peer resources Safety does not mean that requests do not have side effects. For example, many API development platforms limit the traffic of requests. GitHub, for instance, restricts unauthenticated requests to only 60 per hour.

However, clients do not make these GET or HEAD requests in pursuit of side effects; side effects are the server's "unauthorized" actions.

Additionally, when designing the server, it should not allow side effects to be too significant, as clients believe these requests will not produce side effects.

Even if you use each verb according to its original intent, you can still easily prohibit the caching mechanism. The simplest approach is to add a header like this to your HTTP response: Cache-control: no-cache. However, you also lose the support of efficient caching and re-validation (using mechanisms like ETag).

For clients, when implementing a program client for a RESTful service, they should also make full use of existing caching mechanisms to avoid re-fetching representations each time.

HTTP response codes can be used for various situations, and the correct use of these status codes means that clients and servers can communicate at a level with richer semantics.

For example, the 201 ("Created") response code indicates that a new resource has been created, and its URI is in the Location response header.

If you do not utilize the rich application semantics of HTTP status codes, you will miss the opportunity to improve reusability, enhance interoperability, and increase loose coupling.

If these so-called RESTful applications must provide error messages through response entities, then SOAP is the case, and it can meet the requirements.

2.3 Representation of Resources

As mentioned earlier, clients can obtain resources through HTTP methods, right? No, to be precise, what clients obtain is only the representation of the resources. The specific presentation of resources in the outside world can have multiple representation (or manifestation, expression) forms, and what is transmitted between clients and servers is also the representation of the resources, not the resources themselves. For example, text resources can be in html, xml, json, and other formats, and images can be displayed in PNG or JPG.

The representation of resources includes data and metadata that describe the data, such as the HTTP header "Content-Type," which is a metadata attribute.

So, how does the client know which representation format the server provides?

The answer is through HTTP content negotiation. The client can request a specific format of representation through the Accept header, and the server informs the client of the resource's representation format through Content-Type.

Taking GitHub as an example, requesting the JSON representation format of a certain organization's resources:

If GitHub also supports the XML representation format, the result would be as follows:

Let's look at some common practices in design:

Including version numbers in URIs

Some APIs include version numbers in URIs, such as:

If we understand version numbers as different representation forms of resources, we should only use one URL and distinguish them through the Accept header, still taking GitHub as an example, its complete Accept format is: application/vnd.github[.version].param[+json]

For version 3, it would be Accept: application/vnd.github.v3. For the above example, the same can be used with the following headers:

Using URI suffixes to distinguish representation formats

Frameworks like Rails support using /users.xml or /users.json to distinguish different formats. This approach is undoubtedly more intuitive for clients but confuses the resource name and the resource representation format. I personally believe that content negotiation should be prioritized to distinguish representation formats.

How to handle unsupported representation formats

What should be done when the server does not support the requested representation format? If the server does not support it, it should return an HTTP 406 response, indicating a refusal to process the request. Below is an example of a request for an XML representation resource on GitHub:

2.4 Linking Resources

We know that REST uses standard HTTP methods to operate on resources, but understanding it as a web database architecture with CRUD is too simplistic.

This anti-pattern ignores a core concept: "hypermedia as the engine of application state." What is hypermedia?

When you browse web pages, jumping from one link to a page, and then from another link to another page, you are utilizing the concept of hypermedia: linking resources together.

To achieve this, it is required to add links to the representation format to guide the client. In the book "RESTful Web Services," the author refers to this link-

❮ Bubble Sort Js Filter Table ❯