RESTFul服务接口编码规范

版本（Versioning）

        所有的API必须保持向后兼容，必须在引入新版本API的同时确保旧版本API仍然可用。所以应该为其提供版本支持。必须在URL中嵌入版本编号，格式要求如下：

        http://URL/api/v1/*

端点（Endpoints）

        端点就是指向特定资源或资源集合的URL。在端点的设计中，必须遵守下列约定：

       1、URL的命名 必须全部小写

        2、URL中资源（resource）的命名必须是名词，并且必须是复数形式

        3、必须优先使用 Restful类型的URL

        4、URL 必须是易读的

        5、URL 一定不可暴露服务器架构

        6、分页查询使用page区分

       7、批量操作使用list区分

HTTP动词

       对于资源的具体操作类型，由HTTP动词表示。常用的 HTTP动词有下面五个（括号里是对应的 SQL命令）。

       GET（SELECT）：从服务器取出资源（一项或多项）。

        POST（CREATE）：在服务器新建一个资源。

        PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。

      PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。

      DELETE（DELETE）：从服务器删除资源。

响应（Response）

       所有的API响应，必须遵守 HTTP设计规范，必须选择合适的 HTTP状态码。一定不可所有接口都返回状态码为 200的 HTTP响应.

      下表列举了常见的HTTP状态码：

      1xx代表请求已被接受，需要继续处理

      2xx请求已成功，请求所希望的响应头或数据体将随此响应返回

      3xx重定向

      4xx客户端原因引起的错误

     5xx服务端原因引起的错误

       只有来自客户端的请求被正确的处理后才能返回2xx的响应，所以当 API 返回 2xx 类型的状态码时，前端 必须 认定该请求已处理成功。

       必须强调的是，所有API 一定不可返回 1xx类型的状态码。当 API发生错误时，必须返回出错时的详细信息并直接放入响应实体中。

        应该在返回的错误信息中，同时包含面向开发者和面向用户的提示信息，前者可方便开发人员调试，后者可直接展示给终端用户查看如：

{

"message": "直接展示给终端用户的错误信息",

"error_code": "业务错误码",

"error": "供开发者查看的错误信息",

}