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.

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

Referring to the idea of HTTP status code, we segment the error code

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

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