restful接口规范

REST 简介

在 2000 年，Roy Fielding 提议使用表述性状态转移 (REST) 作为设计 Web 服务的体系性方法。 REST 是一种基于超媒体构建分布式系统的架构风格。 REST 独立于任何基础协议，并且不一定绑定到 HTTP。但是，最常见的 REST 实现使用 HTTP 作为应用程序协议，本指南重点介绍如何设计适用于 HTTP 的 REST API。

基于 HTTP 的 REST 的主要优势在于它使用开放标准，不会绑定 API 的实现，也不会将客户端应用程序绑定到任何具体实现。例如，可以使用 ASP.NET 编写 REST Web 服务，而客户端应用程序能够使用任何语言或工具来发起 HTTP 请求和分析 HTTP 响应。

原则

下面是使用 HTTP 设计 RESTful API 时的一些主要原则：

URL中不能有动词
URL结尾不应该包含斜杠“/”
URL路径中首选小写字母
URL路径名词均为复数

请求

所有后台的服务的请求需要加上 api 的前缀，来表示接口。

api.xxx.com/api/

版本

API 的版本号和客户端 APP 的版本号是毫无关系的，不要让 APP 将它们用于提交应用市场的版本号传递到服务器，而是提供类似于v1、v2之类的 API 版本号。版本号只允许枚举，不允许判断区间。

版本号拼接在 URL 中或是放在 Header 中都可以。例如：

api.xxx.com/api/v1/users

方法

HTTP 协议定义了大量为请求赋于语义的方法。大多数 RESTful Web API 使用的常见 HTTP 方法是：

GET 检索位于指定 URI 处的资源的表示形式。响应消息的正文包含所请求资源的详细信息。
POST 在指定的 URI 处创建新资源。请求消息的正文将提供新资源的详细信息。请注意，POST 还用于触发不实际创建资源的操作。
PUT 在指定的 URI 处创建或替换资源。请求消息的正文指定要创建或更新的资源。
PATCH 对资源执行部分更新。请求正文包含要应用到资源的一组更改。
DELETE 删除位于指定 URI 处的资源。

path设计

一般来说 API 的外在形式无非就是增删改查（当然具体的业务逻辑肯定要复杂得多），而查询又分为详情和列表两种，在 RESTful 中这就相当于通用的模板。例如针对文章（Article）设计 API，那么最基础的 URL 就是这几种：

GET /articles：文章列表
GET /articles/id：文章详情
POST /articles/：创建文章
PUT /articles/id：修改文章
DELETE /articles/id：删除文章

RESTful 中使用 GET、POST、PUT 和 DELETE 来表示资源的查询、创建、更改、删除，并且除了 POST 其他三种请求都具备幂等性（多次请求的效果相同）。需要注意的是 POST 和 PUT 最大的区别就是幂等性，所以 PUT 也可以用于创建操作，只要在创建前就可以确定资源的 id。

将 id 放在 URL 中而不是 Query Param 的其中一个好处是可以表示资源之间的层级关系，例如文章下面会有评论（Comment）和点赞（Like），这两项资源必然会属于一篇文章，所以它们的 URL 应该是这样的：

评论：

GET /articles/aid/comments：某篇文章的评论列表
GET /comments/cid：获取
POST /articles/aid/comments：在某篇文章中创建评论
PUT /comments/cid：修改评论
DELETE /comments/cid：删除评论

这里有一点比较特殊，永远去使用可以指向资源的的最短 URL 路径，也就是说既然/comments/cid已经可以指向一条评论了，就不需要再用/articles/aid/comments/cid特意的指出所属文章了。

点赞：

GET /articles/id/like：查看文章是否被点赞
PUT /articles/id/like：点赞文章
DELETE /articles/id/like：取消点赞

RESTful 中不建议出现动词，所以可以将这种关系作为资源来映射。并且由于大部分的关系查询都与当前的登录用户有关，所以也可以直接在关系所属的资源中返回关系状态。例如点赞状态就可以直接在获取文章详情时返回。注意这里我选择了 PUT 而不是 POST，因为我觉得点赞这种行为应该是幂等的，多次操作的结果应该相同。

资源字段查询

/api/v1/users/?gender=1 直接作为gender来传入

资源统计

路径：/api/tableName/count 返回：

{
    "code": 100,
    "msg": "成功",
    "data": {
        total:100
    }
}

参数设计

分页请求

/api/v1/users/?offset=10&limit=10 offset 表示偏移量，limit返回数据个数

排序

-表示降序排列的方式,不加-表示升序 /api/v1/users/?sort=-create_date

根据多个字段排序使用 /api/v1/users/?sort=-create_date,update_date

响应

HTTP CODE

尽量使用 HTTP 状态码，常用的有：

200：请求成功 201：创建、修改成功 204：删除成功 400：参数错误 401：未登录 403：禁止访问 404：未找到 500：系统错误

但是有些时候仅仅使用 HTTP 状态码没有办法明确的表达错误信息。

返回结构

code 代表系统内具体的编码，msg 代表对应的信息。

成功时：

{
    "code": 100,
    "msg": "成功",
    "data": {}
}

失败时：

{ "code": -1000, "msg": "用户名或密码错误" }

分页

{
    "code": 100,
    "msg": "成功",
    "total":100
    "message": []
}

REST 简介​

原则​

请求​

版本​

方法​

path设计​

资源字段查询​

资源统计​

参数设计​

分页请求​

排序​

响应​

HTTP CODE​

返回结构​

分页​

参考​