How to design an API interface that looks like a cow

This article comes from a variety of sources: Java Journey Author: Zhou Mingxuan

In ordinary work, always come into contact with a variety of interfaces. F ront-end data transfer interface, third-party business platform interface. T he front and rear data transmission interfaces of a platform typically communicate in an intranet environment and use a security framework, so security can be well protected. T his article focuses on how the business interfaces provided to third-party platforms should be designed. What questions should we consider?

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

A security issue

Security issues are a specification that an interface must guarantee. If the interface does not guarantee security, then your interface is equivalent to being exposed directly to the public network environment.

1.1 Call the prerequisite for the interface - token

Getting token typically involves several parameters appid appkey timestamp nonce sign We use the above parameters to get the credentials to call the system.

appid and appkey can be requested directly online or issued offline. appid is globally unique, each appid will correspond to one customer, and appkey needs to be highly confidential.

timestamp is a timestamp that uses the system's current unix timestamp. T he purpose of the timestamp is to mitigate DOS attacks. A lways try to request an interface after preventing requests from being intercepted. The server side sets the timestamp threshold, and if the request timestamp and server time exceed the threshold, the response fails.

nonce is a random value. Random values are primarily intended to increase the variability of sign but also to protect the idempotentness of the interface, two adjacent nonce do not allow repetition, if the repetition is considered a duplicate commit, the response fails.

sign is a parameter signature that stitches appkey timestamp nonce together for md5 encryption (and, of course, irreversible encryption in other ways).

token using the appid timestamp nonce sign to get token, as the only credential for system calls. token can set the timeliness once (which is more secure) or the timeliness is set, which is recommended here. I f valid at once, the frequency of requests for this interface can be high. token recommends adding to the request head so that it is completely distinguished from the business parameters.

1.2 Use POST as an interface request

The two most common ways to call interfaces in general are GET and POST. T he difference between the two is also obvious, with GET requests exposing parameters to browser URLs and limiting length. For greater security, all interfaces are requested in POST mode.

1.3 Client IP whitelist

Ip whitelisting is the opening of access to interfaces to some ips. T his avoids other ip access attacks, and one of the tricks of setting up ip whitelists is that when your client migrates, you need to reconnect with the service provider to add a new ip whitelist. T here are many ways to set up ip whitelisting, and in addition to traditional firewalls, the component sentinel provided by spring cloud alibaba also supports whitelisting. To reduce the complexity of the api, it is recommended to use firewall rules for whitelisting.

1.4 A single interface is limited to ip

The current limit is for better maintenance of system stability. The number of interface calls is counted using redis, the ip-interface address as key, the number of accesses as value, and each request for value-1, setting the expiration time to limit the frequency of calls to the interface.

1.5 Log the interface request

Use aop global records to log requests, quickly locate abnormal request locations, and troubleshoot the cause of problems.

1.6 Sensitive data desensitization

Sensitive data such as order numbers may be involved in interface calls, which often require desensitization, most commonly encryption. E ncryption uses high-security RSA asymmetric encryption. T he asymmetric encryption algorithm has two keys that are completely different but match exactly. The encryption and decryption of clear text can only be completed using a matching pair of public and private keys.

2 idempotent issues

Idempotentness means that the execution result of any multiple request has the same effect as the execution result of a request. T o be honest, query operations do not affect the data itself no matter how many times they are queried, so the query operation itself is idempotent. But with new operations, the database changes every time it is executed, so it is non-idempotent.

There are many ideas for solving problems such as power, and here is a more rigorous one. P rovides an interface for generating random numbers, which are globally unique. A random number is brought in when the interface is called. O n the first call, after successful business processing, the random number is used as key, the result of the operation is valued, stored in redis, and the expiration time is set. The second call, querying redis, if key exists, proves to be a duplicate commit, returning the error directly.

Three data specification issues

3.1 Version control

A well-established set of API documentation that, once published, is not allowed to modify the interface at will. A t this time, if you want to add or modify the interface, you need to add version control, version number can be an integer type, or a floating point type. General interface addresses come with a version number, http://ip:port//v1/list

3.2 Response status code specification

A API also needs to provide a simple and straightforward response value, according to the status code can probably know the problem. W e encapsulate data using http status codes, such as 200 for successful requests, 4xx for client errors, and 5xx for errors inside the server. The status code design reference is as follows:

Status code enumeration class:

public enum CodeEnum {


    // 根据业务需求进行添加
    SUCCESS(200,"处理成功"),
    ERROR_PATH(404,"请求地址错误"),
    ERROR_SERVER(505,"服务器内部发生错误");

    
    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 Uniform response data format

To facilitate the response to the client, the response data consists of three properties, the status code, the information description, and the response data. The client quickly knows the interface based on the status code and information description, and if the status code returns successfully, starts processing the data.

Response result definitions 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;
    }


    /**
     * 放入响应枚举
     */
    public R fillCode(CodeEnum codeEnum){
        this.setCode(codeEnum.getCode());
        this.setMessage(codeEnum.getMessage());
        return this;
    }


    /**
     * 放入响应码及信息
     */
    public R fillCode(int code, String message){
        this.setCode(code);
        this.setMessage(message);
        return this;
    }


    /**
     * 处理成功，放入自定义业务数据集合
     */
    public R fillData(Object data) {
        this.setCode(CodeEnum.SUCCESS.getCode());
        this.setMessage(CodeEnum.SUCCESS.getMessage());
        this.data = data;
        return this;
    }
}

summary

This article discusses API design specifications in terms of security, idempotentness, data specifications, and more. B eyond that, a good API is a good interface document. T he readability of interface documents is important, although many programmers don't like to write documents and don't like others not writing documents. In order not to increase the pressure on programmers, it is recommended to use swagger or other interface management tools, which can be easily configured to test interface connectivity in development, and to generate offline documents to manage APIs when online.

The above is W3Cschool编程狮 on how to design a seemingly API interface related to the introduction, I hope to help you.