Debunking the "POST only" API myth, explaining why it stems from a misunderstanding of API design principles, and clarifies the appropriate use cases for RESTful and RPC architectural styles.
Recently, a discussion about whether to design APIs using "POST only" caught my attention. After delving into this debate, I found that not only is the issue people are arguing about meaningless, but it also exposes many developers' misunderstanding of the essence of API design. Today, let's dive deep into the core ideas of API design and see why this debate shouldn't exist in the first place.
Those developers who advocate using "POST only" to replace RESTful API specifications clearly haven't grasped the most important point of API design. Their arguments usually include:
At first glance, these arguments seem to make some sense. But in reality, this view confuses the choice of HTTP methods with API design styles, two different levels of issues. POST is just one method of the HTTP protocol, while REST is a style of API design.
Before discussing specific API styles, we need to understand what the core purpose of API design is. A good API should be:
RESTful API is just one of many API design styles, focusing on resources and operations on resources. Let's take a simple blog system as an example to see how RESTful API is designed:
Get all articles:
Get a specific article:
Create a new article:
Update an article:
Delete an article:
In this example, we can see:
This design approach makes the API more intuitive and self-explanatory, making it easy for developers to understand the function of each endpoint.
The goal of RPC (Remote Procedure Call) style API design is to make remote service calls look as simple as calling local functions.
Interestingly, those advocating for "POST only" may not realize that they are actually describing the RPC style.
Compared to RESTful APIs, RPC focuses more on the operation itself rather than the resource. This is why RPC-style APIs typically use a "verb + noun" form, such as getProduct(productId) or createUser(userData).
In many RPC implementations, all operations are usually sent via POST requests to the same endpoint, with the specific operation and parameters specified in the request body. This is why the idea of "POST only" is actually closer to RPC than REST.
For example, an RPC-style "get product" request based on HTTP might look like this:
Modern RPC frameworks, such as gRPC, provide more powerful and efficient implementations. Let's use this as an example to demonstrate the RPC style:
First, we define the service and message format (using Protocol Buffers):
Then, using this service in a Node.js client is as simple as calling a local function:
In this RPC-style example, we can see:
GetArticle and CreateArticle).await to wait for the result, which further hides the complexity of network communication.Although the underlying layer may still use HTTP/2 as the transport protocol, RPC frameworks (such as gRPC) provide developers with an abstraction layer that makes remote calls look and feel like local function calls.
Therefore, we can see that most of the debates about "POST only" and RESTful APIs should essentially be discussions about these two API styles: REST and RPC. However, the key is to recognize that these two styles each have their applicable scenarios, and the choice should be based on the specific needs of the project, not personal preference.
Now that we understand the differences between REST and RPC, let's look at their respective applicable scenarios:
The choice of style should be based on your specific needs. In some cases, you might even use a mix of these two styles within the same system to meet the needs of different parts.
Let's shift our attention away from these pointless arguments and focus on designing truly excellent APIs. After all, technology is for solving problems, not creating them.