How to design a powerful API interface

[[343143]]

In daily development, we always come into contact with various interfaces. Front-end and back-end data transmission interfaces, third-party business platform interfaces. The front-end and back-end data transmission interfaces of a platform generally communicate in an intranet environment and use a security framework, so security can be well protected. This article focuses on how to design the business interface provided to the third-party platform? What issues should we consider?

A secure API interface is designed mainly from the above three aspects.

A security issue

Security is a specification that an interface must ensure. If the interface cannot ensure security, then your interface is equivalent to being directly exposed to the public network environment and being ravaged by anyone.

1.1 Prerequisites for calling the interface - token

Getting a token generally involves several parameters: appid, appkey, timestamp, nonce, and sign. We use the above parameters to obtain the credentials for calling the system.

AppID and AppKey can be applied online or issued offline. AppID is globally unique, each AppID corresponds to one customer, and AppKey needs to be highly confidential.

timestamp is the timestamp, using the current Unix timestamp of the system. The purpose of the timestamp is to mitigate DOS attacks. It prevents the request from being intercepted and then trying to request the interface again. The server sets the timestamp threshold. If the request timestamp and server time exceed the threshold, the response fails.

Nonce is a random value. The purpose of the random value is to increase the variability of the sign and to protect the idempotence of the interface. The nonce of two consecutive requests is not allowed to be repeated. If repeated, it is considered a duplicate submission and the response fails.

sign is the parameter signature, which concatenates appkey, timestamp, and nonce for md5 encryption (of course, it is also OK to use other methods for irreversible encryption).

Token, use the parameters appid, timestamp, nonce, sign to obtain a token, which is used as the only credential for system calls. The token can be set to be valid once (which is more secure) or to have a time limit. It is recommended to set the time limit. If it is valid once, the request frequency of this interface may be very high. It is recommended to add the token to the request header so that it can be completely distinguished from the business parameters.

1.2 Use POST as the interface request method

The two most commonly used methods for calling interfaces are GET and POST. The difference between the two is also obvious. GET requests will expose parameters in the browser URL and have length restrictions. For higher security, all interfaces use POST requests.

1.3 Client IP Whitelist

IP whitelisting means opening the access rights of the interface to some IPs. This can prevent other IPs from accessing and attacking. The troublesome thing about setting up an IP whitelist is that after your client is migrated, you need to contact the service provider again to add a new IP whitelist. There are many ways to set up an IP whitelist. In addition to traditional firewalls, the component sentinel provided by Spring Cloud Alibaba also supports whitelisting. In order to reduce the complexity of the API, it is recommended to use firewall rules to set up whitelists.

1.4 Limiting the flow of a single interface for IP

The purpose of current limiting is to better maintain system stability. Use redis to count the number of interface calls, with IP+interface address as the key and the number of visits as the value. Each request is value+1, and the expiration time is set to limit the frequency of interface calls.

1.5 Recording interface request logs

Use aop to globally record request logs, quickly locate abnormal request locations, and troubleshoot the causes of problems.

1.6 Desensitizing sensitive data

During the interface call process, sensitive data such as order numbers may be involved. Such data usually needs to be desensitized, and the most common method is encryption. The encryption method uses RSA asymmetric encryption with relatively high security. The asymmetric encryption algorithm has two keys, which are completely different but completely matched. Only by using a matching pair of public and private keys can the encryption and decryption process of plain text be completed.

Idempotence Problem

Idempotence means that the results of executing any number of requests have the same impact as the results of executing a single request. To put it bluntly, the query operation will not affect the data itself no matter how many times it is queried, so the query operation itself is idempotent. However, if a new operation is added, the database will change every time it is executed, so it is non-idempotent.

There are many ways to solve the idempotence problem. Here is a more rigorous one. Provide an interface for generating random numbers. The random numbers are globally unique. Bring in the random number when calling the interface. The first time the business is successfully processed, the random number is used as the key and the operation result is used as the value. Store it in redis and set the expiration time. The second time the key is called, query redis. If it exists, it proves that it is a duplicate submission, and an error is returned directly.

Three data standardization issues

3.1 Version Control

Once a mature API document is released, it is not allowed to modify the interface at will. At this time, if you want to add or modify the interface, you need to add version control. The version number can be an integer type or a floating point type. Generally, the interface address will have a version number, http://ip:port//v1/list.

3.2 Response Status Code Specification

A good API also needs to provide simple and clear response values. The status code can roughly tell where the problem lies. We use the http status code to encapsulate data. For example, 200 indicates a successful request, 4xx indicates a client error, and 5xx indicates an internal server error. The status code design reference is as follows:

Status code enumeration class:

 public enum CodeEnum { 
 
 // Add according to business needs
 SUCCESS(200, "Processing successful" ) ,
 ERROR_PATH(404, "Wrong request address" ) ,
 ERROR_SERVER(505, "Internal server error" ); 
     
 private int code;
 private String message; 
     
    CodeEnum( int code, String message) {
 this.code = code;
        this.message = message;
 } 
 
 public   int getCode() {
 return code;
 } 
 
 public void setCode( int code) {
 this.code = code;
 } 
 
 public String getMessage() {
 return message;
 } 
 
 public void setMessage(String message) {
        this.message = message;
 }
 }

3.3 Unified response data format

In order to respond to the client conveniently, the response data will contain three attributes: status code (code), information description (message), and response data (data). The client can quickly know the interface based on the status code and information description. If the status code returns success, it will start processing the data.

Response result definition and common methods:

 public class R implements Serializable { 
 
    private static final long serialVersionUID = 793034041048451317L; 
 
 private int code;
 private String message;
    private Object data = null ; 
 
 public   int getCode() {
 return code;
 }
 public void setCode( int code) {
 this.code = code;
 } 
 
 public String getMessage() {
 return message;
 }
 public void setMessage(String message) {
        this.message = message;
 } 
 
 public Object getData() {
 return data;
 } 
 
 /**
 * Put in the response enumeration
 */
 public R fillCode(CodeEnum codeEnum){
        this.setCode(codeEnum.getCode());
        this.setMessage(codeEnum.getMessage());
 return this;
 } 
 
 /**
 * Enter the response code and information
 */
 public R fillCode( int code, String message){
 this.setCode(code);
        this.setMessage(message);
 return this;
 } 
 
 /**
 * Processing successful, put into custom business data collection
 */
 public R fillData(Object data) {
        this.setCode(CodeEnum.SUCCESS.getCode());
        this.setMessage(CodeEnum.SUCCESS.getMessage());
 this.data = data;
 return this;
 }
 }

Summarize

This article discusses API design specifications from the aspects of security, idempotence, data specifications, etc. In addition, a good API cannot be without an excellent interface document. The readability of the interface document is very important, although many programmers do not like to write documents, and do not like others not to write documents. In order not to increase the pressure on programmers, it is recommended to use swagger or other interface management tools. Through simple configuration, the connectivity of the interface can be tested during development, and offline documents can also be generated after going online for API management.

This article is reprinted from the WeChat public account "Java Journey", which can be followed through the following QR code. To reprint this article, please contact the Java Journey public account.