How to design API return code (error code)?
I. Introduction
When the client requests the API, it usually needs to use the return code to judge whether the result returned by the API meets expectations, and how to deal with the returned content, etc.
I believe that many students have suffered from the confusion of return code definitions. Some APIs use return codes of int type, some of which are string types, some use 0 to indicate success, some use 1 to indicate success, and some use "true" to indicate success. When something like this happens, all I can say is: headache
The design of the API return code should be taken seriously, after all, a good return code design can reduce communication costs and program maintenance costs
2. HTTP status code reference
Taking the HTTP status code as an example, in order to express and distinguish the meaning of the status code more clearly, the HTTP status is segmented.
section | segment description |
---|---|
1XX | Information, the server receives the request and needs the requester to continue to perform the operation |
2XX | Success, the operation was successfully received and processed |
3XX | Redirected, further action is required to complete the request |
4XX | Client error, the request contained syntax errors or could not be completed |
5XX | Server error, the server encountered an error while processing the request |
For back-end development, what we usually see are:
2XX status code, such as 200->request succeeded,
5XX status code, such as 502->server exception, usually means that the service is not running normally, or the code execution error
The cause of the problem can be preliminarily judged by the status code, and the design idea of the HTTP status is worth learning.
3. Parameter convention
Although it is a return code design, only the code is not enough, and there must be a corresponding message so that people can understand it
field | type | illustrate |
---|---|---|
code | int | return code |
message | string | Return Code Description |
Referring to the idea of HTTP status code, we segment the error code
return code value | illustrate |
---|---|
0 | success |
99999 | An unknown exception occurred in the system |
10000-19999 | Parameter validation error |
20000-29999 | A step execution failed |
30000-39999 | Step B failed to execute |
Through this design, both programs and people can easily distinguish the returned results of the API, the key is unity!
4. Personalized Message
Usually our messages are written for engineers to read, but in different scenarios, the same error may require users to see different error prompts.
For example, 20000-29999 indicates that the order creation failed:
20001, order creation failed, there are orders in progress
20002, order creation failed, the last order is being queued for creation
If these two error situations are for users, they may only be suitable for viewing: Sorry, you have an order in progress, please go to my order list to process it.
But for the API, the information returned must be accurate, but what the user sees must be translated. This translation can be done by the caller, but usually it is better for the API provider to provide personalized Message capabilities.
We can configure the translated message to the database and cache it to Redis or API native
application_id | code | message |
---|---|---|
100001 | 20001 | Sorry, you have an order in progress, please go to my order list to process it. |
100001 | 20002 | Sorry, you have an order in progress, please go to my order list to process it. |
Then when the request processing is finished and is about to return, match and replace the message according to the application_id+code
In this way, we can allow users of mobile APPs, users of WeChat applets, and corporate users who place orders on the web to see different messages.
5. Unified processing of returned information
With a unified code, we can use Nginx or APM tools to count the number and distribution of API request codes.
We can make API exception alarms based on the number of 99999 per unit time
We can help us find problems in the system and business process according to the pie chart returned by Code
etc.
In short, a good return code design can help us improve communication efficiency and reduce code maintenance costs
0 Comments