频道栏目
首页 > 程序开发 > 软件开发 > 其他 > 正文
RESTful API接口设计
2016-12-30 09:36:13         来源:Ricky  
收藏   我要投稿

RESTful API接口设计:URL设计,URL既统一资源定位符。数据交换格式。可选:XML、JSON,Protobuf。XML、JSON大家应该都很熟悉了,这里介绍一下Protobuf。

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

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

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

服务器返回的数据结构,一般如下:

/**
 * ${DESCRIPTION}
 *
 * @author Ricky Fung
 * @date 2016-12-29 14:21
 */
public class ResponseEntity 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 setCode(int code) {
        this.code = code;
        return this;
    }

    public String getMessage() {
        return message;
    }

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

    public T getData() {
        return data;
    }

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

    public static  ResponseEntity 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

接口版本管理

接口版本

点击复制链接 与好友分享!回本站首页
上一篇:SSH框架之Hibernate的二级缓存
下一篇:高并发下的下单功能设计
相关文章
图文推荐
点击排行

关于我们 | 联系我们 | 广告服务 | 投资合作 | 版权申明 | 在线帮助 | 网站地图 | 作品发布 | Vip技术培训 | 举报中心

版权所有: 红黑联盟--致力于做实用的IT技术学习网站