Restful APIs: Should We Only Use the POST Method?

Today on my X (Twitter) timeline, I saw a tweet where the original poster mentioned that when redesigning their API, they replaced all GET methods with POST methods, and called the design philosophy of RESTful APIs “dogmatic formalism.”

Personally, I feel this statement is a bit extreme. Without describing specific business scenarios, such a claim could mislead inexperienced beginners.

In the replies to this tweet, many people agreed with removing the GET method and listed some business scenarios. I’ve summarized these arguments roughly as follows:

Tip

Limitations of the GET Method

Parameter Transmission Limits: The GET method has significant limitations in passing parameters, as all parameters must be included in the URL.

Cannot Carry a Request Body: GET requests cannot include a request body; data can only be passed via URL parameters.

URL Length Limits: The maximum URL length is typically limited to around 2000 characters, which may not meet complex query requirements.

Exposure of Sensitive Information: Parameters in the URL may be recorded in web server logs, posing a risk of sensitive information leakage.

Complex Query Syntax: As project complexity increases, GET request query parameters can become cumbersome and difficult to manage.

Although these limitations of the GET method do exist, I personally believe that when designing RESTful APIs, adhering to its design principles as much as possible is more beneficial for API maintainability and scalability.

Below, I will delve into the definition of RESTful APIs, their core principles, and common issues to explore whether we should exclusively use the POST method.

What is a RESTful API?

To evaluate whether we should only use the POST method, we first need to revisit the definition of a RESTful API.

Important

A RESTful API is an Application Programming Interface (API) that adheres to the REST (Representational State Transfer) architectural style. It provides a standardized way for web applications to communicate with each other over the internet.

Core Ideas and Principles of REST

REST is not a specific technical standard but a series of design principles and constraints. These mainly include:

Client-Server:

Separation of concerns between the client and server. The client is responsible for the user interface, and the server is responsible for data storage and processing. This separation enhances the cross-platform portability of the client and the scalability of server components.

Stateless:

The server does not store client context information. Each request from the client must contain all the information necessary for the server to process the request. This allows the server to handle each request independently, reducing server load and improving system scalability and reliability.

Cacheable:

Server responses can be cached by the client or intermediate layers (like proxy servers). This helps reduce network traffic, improving performance and user experience.

Uniform Interface:

This is a core feature of the REST architectural style, simplifying the architecture and decoupling the system through a standardized interface. The uniform interface includes the following sub-principles:

• Resource Identification: Each resource should have a unique identifier, usually a URI (Uniform Resource Identifier). These resources should use nouns rather than verbs. For example, use /users/123 instead of /getUser?id=123.
• Manipulation of resources through representations: Clients manipulate resources through their representations (e.g., JSON or XML formatted data).
• Self-descriptive Messages: Each message (request or response) should contain enough information for the receiver to understand it without needing to refer to external documentation.
• Hypermedia as the Engine of Application State (HATEOAS): Responses should include links to guide the client in discovering other available resources and operations.

Layered System:

The client does not need to know whether it is connected directly to the end server or through an intermediary layer (like a load balancer). This layered design improves system flexibility and scalability.

Core Idea of RESTful APIs

RESTful APIs follow REST principles, with the core idea being to use HTTP methods to represent operations on resources. Standard HTTP methods correspond to CRUD (Create, Read, Update, Delete) operations as follows:

• GET: Used to read resources. The result should be the same no matter how many times it’s executed (idempotent).
• POST: Used to create new resources. Can also be used for certain update operations or to perform specific actions.
• PUT: Used to fully update an existing resource. If the resource does not exist, it can sometimes be used to create the resource (depending on the specific implementation).
• DELETE: Used to delete resources.
• PATCH: Used to partially update an existing resource.

These methods provide clear semantics for resource operations and are the foundation of RESTful API design.

Common Issues in RESTful API Implementation

Although the core ideas and design principles above seem clear, developers often deviate from REST principles in actual RESTful API design. Here are some common problems and suggestions for improvement.

Resource Identifiers Containing Verbs

REST principles recommend using nouns to identify resources, for example, /users instead of /get-users. For simple CRUD operations, this approach is easy to implement:

However, when dealing with complex operations (like “activate user,” which might involve sending emails, initializing data, logging, and a series of complex business logic), developers might be inclined to use verbs. For example:

Warning

“Not Recommended”

POST /users/{id}/activate

The POST request body would contain the information needed for user activation.

This design is intuitive, but as the project scale grows, the use of verbs can lead to an inconsistent API style.

A Different Approach

Consider “activating a user” as a new resource, /userActivations, designed as follows:

• POST /userActivations : Create an activation request; the request body contains user information.
• Response:
  • 201 Created: Indicates the activation request was successfully created. The response body can include details of the new activation request.
  • 202 Accepted: If activation is an asynchronous process that takes time, return 202 to indicate the server has accepted the request for processing but has not yet completed it. The client can later query the activation status via GET /userActivations/{newRequestID}.

This design adheres to REST principles, maintains interface uniformity, and supports complex operations.

Whether to Use Multi-Level URLs

In resource identification design, there’s debate about whether to use multi-level URLs. For example, to get a specific article by a certain author:

• Approach One: GET /authors/{id}?articleid={articleid} (using query parameters)
• Approach Two: GET /authors/{id}/articles/{articleid} (multi-level URL)

Although ‘Approach One’ makes the resource identifier URL look simpler and offers more flexibility, I prefer the second approach. It clearly expresses the hierarchical relationship between resources, such as ‘an article belongs to an author.’ Moreover, on the server-side, access permissions can be easily managed through routing.

However, if the data hierarchy is complex, excessive nesting can occur, for example:

• Approach One: GET /authors/{id}/articles?categoryid={categoryid}
• Approach Two: GET /authors/{id}/categories/{categoryid}/articles

Which approach to use requires weighing the trade-offs based on the scenario. If you want to access data according to a strict resource hierarchy, you can choose ‘Method Two.’ If the calling location requires flexibility and other conditions for querying articles might be added later, ‘Method One’ can be chosen.

Use of HTTP Response Codes

RESTful APIs use HTTP methods to identify operations on resources and HTTP response codes to indicate resource status. However, in actual API design, developers typically have two approaches:

1. Service-oriented: Treat the API as a service. If the service is available, return 200 OK; if unavailable, return 404, 500, etc. A custom status code is included in the response body:

{
    "code": 201,
    "message": "Response Message",
    "data": {},
}

2. Resource-oriented: Treat the API as resource access. HTTP response codes directly reflect the resource status: 200 OK for success, 404 if the resource doesn’t exist, 201 for successful creation, 400 for a bad request, etc. The response body is used only for data transfer.

It’s not hard to see that Method Two is more aligned with REST principles. The URL is the resource identifier, and taking the 404 response code as an example, it uniformly expresses that the resource does not exist, regardless of whether the cause is network-related, server-related, or due to business logic.

Should We Only Use the POST Method?

Whether to exclusively use the POST method in a RESTful API depends on the specific scenario. If a project is better suited for RPC (Remote Procedure Call) rather than REST, it’s better to switch to RPC. In RESTful API scenarios, REST principles should be prioritized.

Let’s analyze the limitations of the GET method one by one:

1. URL Length Limits: The URL length of a GET request is limited. For complex queries, if you simply serialize JSON-structured query parameters, convert them to Base64, and pass them in query parameters, you might exceed the length limit. A better solution is to first optimize the query parameters and then implement a mapping conversion from the JSON structure to query parameters.
2. Exposure of Sensitive Information: The URL of a GET request might be logged, leaking sensitive data. The solution is to use encryption methods to encrypt sensitive data before transmission.
3. Complex Queries: GET request query parameters can become cumbersome as project complexity increases. It’s advisable to distinguish between queries (supported by the API) and filters (which can be implemented client-side). This reduces the number of query parameters and lessens the burden on the server.

Despite the limitations of the GET method, the design of RESTful APIs should still prioritize adherence to its core principles: using standard HTTP methods, noun-based resource identifiers, and a uniform interface.

These principles help build maintainable and scalable APIs. For complex queries or scenarios involving sensitive information, the POST method is a reasonable supplement but should not completely replace the GET method. When designing APIs, developers should weigh REST principles against practical flexibility based on business scenarios, ensuring that API design balances specification with usability.