From Wild API Errors to Structured RESTful Practices: A Top Architect’s Journey

Welcome, I am a top architect sharing a story that began many years ago when AJAX first appeared.

1. The Wild Early Stage

At that time, we defined the API response JSON format as:

{
  "code": 0,
  "msg": "SUCCESS",
  "data": DATA // {},[],null,string,boolean,number
}

We used HTTP status code 200 to indicate normal operation, but without a unified error code standard, failures were chaotic, with only 401 meaning token expiration and other codes being vague.

2. The Architect Arrives

He advocated proper RESTful practices, respecting HTTP status definitions such as:

200 OK – operation succeeded

400 Bad Request – invalid parameters

401 Unauthorized – not logged in or token expired

403 Forbidden – no permission

404 Not Found – resource does not exist

Following RESTful standards, the response body should contain only the data, not another JSON wrapper.

2.1 HTTP Error Codes Are Insufficient

The architect suggested extending codes, e.g., using 601, but later backend introduced 1001 and 2001, which were truncated to three digits, causing misinterpretation on the frontend.

HTTP status codes are limited to three digits; 2001 becomes 200.

2.2 Resource Boundaries Became Messy

When asked where to place login, the architect proposed abstracting a login record resource, leading to many resources like _log and login_log , some backed by real tables, others just to satisfy RESTful naming.

3. The Architect Disappears

Overwhelmed by the issues, the architect left, and the project continued with chaotic practices.

3.1 Project Finally Launched

Unexpected problems arose, such as 404 responses being hijacked to another page.

3.2 Mini‑Program Development

We discovered that WeChat Mini‑Programs do not support the PATCH method, so we added a _method parameter to indicate a PATCH request via PUT.

4. Post‑Modern Renaissance

After refactoring, we decided to abandon strict RESTful conventions.

4.1 Use POST for Everything

All parameters are sent via POST, except for downloads and exports.

4.2 Restore the Original Data Format

{
  "code": 200,
  "message": "SUCCESS",
  "data": DATA // {},[],null,string,boolean,number
}

4.3 New Status Code Rules

We still respect HTTP semantics: 200 means success, others indicate failure, but we use an extensible enumeration (e.g., 4031 for “no permission to create”).

4.4 New Interface Naming Standard

Interfaces are named using verb + adjective + resource , such as getUserInfo , updateOrderStatus , addMyOrder , or deleteAllLog , making their purpose clear from the URL.

5. Conclusion

The purpose of this article is not to argue superiority but to share a real‑world story of API evolution and its pitfalls.

Promotional Section (non‑academic): A special offer for a DeepSeek practical collection, AI community membership, and various AI‑related benefits priced at 29.9 CNY, with additional upsell options and links to other resources.