RESTful API接口设计

RESTful API接口设计

URL设计

URL（Uniform / Universal Resource Locator）既统一资源定位符。

数据交换格式

可选：XML、JSON，Protobuf
XML、JSON大家应该都很熟悉了，这里介绍一下Protobuf。

Protocol buffers are Google’s language-neutral, platform-neutral, extensible mechanism for serializing structured data – think XML, but smaller, faster, and simpler. You define how you want your data to be structured once, then you can use special generated source code to easily write and read your structured data to and from a variety of data streams and using a variety of languages.

Protocol Buffers( 简称 Protobuf) 是 Google 公司内部的混合语言数据标准，是一种轻便高效的结构化数据存储格式，可以用于结构化数据串行化，或者说序列化。它很适合做数据存储或 RPC 数据交换格式。可用于通讯协议、数据存储等领域的语言无关、平台无关、可扩展的序列化结构数据格式。目前提供了 C++、Java、Python 三种语言的 API。

JSON已经成为多种行业标准的编写工具，Protobuf 只是 Google 公司内部使用的工具，在通用性上还差很多。

推荐使用JSON格式，JSON比 XML 更小、更快、也更简单；

服务器返回的数据结构，一般如下：

/**
 * ${DESCRIPTION}
 *
 * @author Ricky Fung
 * @date 2016-12-29 14:21
 */
public class ResponseEntity<T> implements Serializable {

    private static final long serialVersionUID = 3634412846969689145L;

    private int code;
    private String message;
    private  T data;

    public ResponseEntity(){
    }

    public int getCode() {
        return code;
    }

    public ResponseEntity<T> setCode(int code) {
        this.code = code;
        return this;
    }

    public String getMessage() {
        return message;
    }

    public ResponseEntity<T> setMessage(String message) {
        this.message = message;
        return this;
    }

    public T getData() {
        return data;
    }

    public ResponseEntity<T> setData(T data) {
        this.data = data;
        return this;
    }

    public static <T> ResponseEntity<T> create(){
        return new ResponseEntity();
    }

    @Override
    public String toString() {
        StringBuilder sb = new StringBuilder(64);
        sb.append("ResponseEntity{")
                .append("code=")
                .append(code)
                .append(", message='")
                .append(message)
                .append('\'')
                .append(", data=")
                .append(data)
                .append('}');
        return sb.toString();
    }
}

说明：

• code: 返回码，0表示请求成功，非0表示各种不同的错误；
• message: 描述信息，请求成功时为”success”，错误时则是提示文案；
• data: 请求成功时返回的数据，类型为对象或数组；

不同错误需要定义不同的返回码，建议整个接口系统设计一套全局返回码，方便排查错误。例如：

/**
 * 全局返回码
 *
 * @author Ricky Fung
 * @date 2016-12-29 14:49
 */
public interface ResponseCode {

    int SUCCESS = 0; // 请求成功

    int MISSING_PARAMETER = 101; // 缺少请求参数
    int MISSING_APPKEY = 102; // 缺少请求参数
    int MISSING_TOKEN = 103; // 缺少token
    int MISSING__SIGNATURE = 104; // 缺少签名
    int PARAMETER_TYPE_NOT_MATCH = 105;
    int PARAMETER_LENGTH_INVALID = 106;


    int AUTH_VALIDATION_ERROR = 120;  // 安全认证不通过


    int BLOCKING_IP_RANGE = 400;// 非法IP段
    int RESOURCE_NOT_FOUND = 404;

    int REQUEST_FREQUENCY_TOO_HIGH = 410;   //请求频率太快

    int SYSTEM_INTERNAL_ERROR = 500; // 系统内部错误
    int SERVICE_NOT_AVAILABLE = 501; // 服务暂时不可用

}

接口安全认证

OAuth2.0

接口版本管理

接口版本