Remember when we were designing interfaces we didn’t have that many specifications, because the front and back ends weren’t separated. Both the front end and the back end are developed by one person in pursuit of “efficiency”. So – called interface specifications bloom in their own way. Later, the front and back end are separated, and the code that was written for “efficiency” is refactored into the code.

So now the basic institutional system has been basically fixed, and different businesses can be vertically expanded.

There is no “always the best” standard, but there is a big difference between a good back-end interface and a bad one. One of the most important things to look for is specification!

There are many factors to consider when designing interfaces, such as service positioning, security, scalability, stability, cross-region, protocol rules, path rules, single interface rule, interface filtering, and interface combination.

In this paper, the interface return parameters combined with some online case comparison and thinking, to tell how to design the interface return parameters more reasonable.

Business case

Jane the book –

This is probably the worst design I’ve ever seen. Open up a few pages and you can see the interface return parameter design.

{// result set}Copy the code

– the nuggets

After reading Jane’s book, let’s look at another product nuggets, nuggets are relatively better. At least there is an obvious hierarchy of status codes, result sets, successes or errors, but the naming is a bit misleading, at least personally.

{" data ":" result set ", "err_msg" : "success or error message," "err_no" : "status code"}Copy the code

– CSDN

In terms of interface parameters, CSDN is a normal interface. The interface contains three elements: status code, result set, and success or error notification.

{" code ":" status code/result code ", "data" : "the result set/data", "message" : "success/error message"}Copy the code

Such return parameters are qualified for individual services. The state of each interface and the result of the corresponding state are known. If you want to display a hint for the state, you can determine it according to the corresponding message. This design can basically meet the requirements for single service.

– InfoQ

One of the nice things about InfoQ’s interface return value is that there is an extended return parameter design, which includes a parameter cost, which is the interface time.

{" code ":" status code/result code ", "data" : "the result set/data", "error" : "success/error message", "extra" : {" cost ", "cost/time", "the request - id" : "request id"}}Copy the code

The interface return parameter design for InfoQ is much better than the previous products, especially the cost/time statistics for the interface. But it’s a little bit redundant. Why is that? Because browsers come with their own features

Request-id is the link ID of the current requesting thread. Logging is a powerful tool for tracking services in microservices.

Design optimization

Combined with the design of interface return parameters of the above products, several key points of interface return parameters can be summarized

In addition to InfoQ and CSDN, Boolean is added to indicate whether the interface has been successfully executed. Of course, you can also use status codes, but there are some optimizations here.

Consider another common internationalization problem

  • How to unify the national prompt? How to handle internationalization issues with some validation exceptions thrown at the back end?

In fact, it is not particularly difficult to solve the international problem of appeal, so make a little adjustment.

  • The code is changed to messageKey for success/error, and the internationalized key is bound by the front and back ends

  • MSG is changed to: success/error message, which is converted to the corresponding error message by the back end according to the internationalization configuration

{"success": true, "code": "return. OptSuccess ", "MSG ":" your operation succeeded!" , "data": {// data}, "extendProps":{// extension}}Copy the code

The design development

In the basic return information for the expansion of the supplement, in fact, the purpose here is mainly for development and operation personnel to supplement.

What would be your first reaction if an interface returned an error message?

Check back-end logs. However, there are so many logs collected. Based on what information, you can quickly locate problems by querying back-end server logs?

To solve the scenario where log query is difficult to locate, it is recommended to add a link ID, also known as a trace ID, so that the design can be optimized

{"success": true, "code": "return. OptSuccess ", "MSG ":" your operation succeeded!" The "data" : {} / / data, "traceId" : "1 fbovmc1hwu2wc5w2n2n4gm2lmjaoo2b5dw0}"Copy the code

Of course, not all errors need to be viewed in the log, and for some errors, back-end development can throw out the stack information cache if necessary, such as this one

{"success": false, "code": "Initialization exception!" , "traceId": "1fbqterqbwu5wiow1bjvu6214amgrd3i7cw0", "errStacks": [ { "app": "base-service", "code": ". The error. The data dictionary. Conversion ", "message" : "data dictionary serialization anomaly"}}]Copy the code

If you see the stack information for the interface, you can roughly locate the error location of your code. If you still cannot locate the error location, you need to check the specific error location through the link ID. Therefore, you can continue to optimize the returned parameters for the interface

conclusion

With the rapid development of Internet engineering and the popularity of distributed, micro-service and containerized architecture, the Internet has fully entered the cloud native era. The way to build the system has evolved from the original single large application to distributed architecture, without rules, can not become fangyuan. Only by constantly optimizing can we create better products. This issue mainly focuses on interface return parameters combined with some online case comparison and thinking.

In fact, there are many factors to consider when designing an interface, such as the service positioning, security, scalability, stability, cross-region, protocol rules, path rules, single interface rule, interface filtering, and interface combination. Later installments will be shared one by one.

Technical number Address