RESTful API设计规范收集
Posted Jim
tags:
篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了RESTful API设计规范收集相关的知识,希望对你有一定的参考价值。
说明:其实没有绝对的规范,达到90%即可。
理解RESTful架构:http://www.ruanyifeng.com/blog/2011/09/restful.html
RESTful API 设计指南:http://www.ruanyifeng.com/blog/2014/05/restful_api.html
GitHub标准RESTful API:https://api.github.com/
教程收集:
http://imweb.io/topic/5707561f06f2400432c139a5(以下内容转自此篇文章)
http://www.coderli.com/translate-restful-standard-resolved/
http://blog.csdn.net/yue7603835/article/details/52536497
http://blog.csdn.net/u013731455/article/details/56278168
https://www.zhihu.com/question/28557115
URI
URI规范
- 不要用大写
- 单词间使用下划线‘_‘
- 不使用动词,资源要使用名词复数形式,如:user、rooms、tickets
- 层级
>=
三层,则使用‘?‘带参数users/1/address/2/citys(bad) /citys?users=1&address=2; (good)
Request
Method
- GET:查询资源
- POST:创建资源
-
PUT/PATCH
- PUT:全量更新资源(提供改变后的完整资源)
- PATCH:局部更新资源(仅提供改变的属性)
-
DELETE:删除资源
安全性与幂等性
- 安全性:任意多次对同一资源操作,都不会导致资源的状态变化
- 幂等性:任意次对同一资源操作,对资源的改变是一样的
-
Method 安全性 幂等性 GET √ √ POST × × PUT × √ PATCH × √ DELETE × √
兼容
很多客户只支持GET/POST请求,一般有两种方式模拟PUT等请求
- 添加_method参数
/users/1?_method=put&name=111
- 添加X-HTTP-Method-Override请求头 (我们使用这种方式)
X-HTTP-Method-Override: PUT
参数
Method
GET
- 非id的参数使用‘?‘方式传输
/users/1?state=closed
POST、PATCH、PUT、DELETE
- 非id的参数使用body传输,并且应该encode
过滤
?type=1&state=closed
排序
+
升序,如?sort=+create_time,根据id升序-
降序,如?sort=-create_time,根据id降序
分页
?limit=10&offset=10
- limit:返回记录数量
- offset:返回记录的开始位置
单参数多字段
使用,
分隔,如
/users/1?fields=name,age,city
版本控制
三种方案:
- 在uri中加入版本: /v1/room/1
- Accept Header:Accept: v1
- 自定义 Header:X-Imweb-Media-Type: imweb.v1 (我们使用此方案)
自定义Media-Type参考资料github
状态码
成功
Code | Method | Describe |
---|---|---|
200 | ALL | 请求成功并返回实体资源 |
201 | POST | 创建资源成功 |
客户端错误
Code | Method | Describe |
---|---|---|
400 | ALL | 一般是参数错误 |
401 | ALL | 一般用户验证失败(用户名、密码错误等) |
403 | ALL | 一般用户权限校验失败 |
404 | ALL | 资源不存在(github在权限校验失败的情况下也会返回404,为了防止一些私有接口泄露出去) |
422 | ALL | 一般是必要字段缺失或参数格式化问题 |
服务器错误
CODE | METHOD | DESCRIBE |
---|---|---|
500 | ALL | 服务器未知错误 |
以上是常见的状态码,完整的状态码列表在这状态码
HATEOAS
在介绍HATEOAS之前,先介绍一下REST的成熟度模型
在介绍 HATEOAS 之前,先介绍一下 Richardson 提出的 REST 成熟度模型。该模型把 REST 服务按照成熟度划分成 4 个层次:
- 第一个层次(Level 0)的 Web 服务只是使用 HTTP 作为传输方式,实际上只是远程方法调用(RPC)的一种具体形式。
- 第二个层次(Level 1)的 Web 服务引入了资源的概念。每个资源有对应的标识符和表达。
- 第三个层次(Level 2)的 Web 服务使用不同的 HTTP 方法来进行不同的操作,并且使用 HTTP 状态码来表示不同的结果。如 HTTP GET 方法来获取资源,HTTP DELETE 方法来删除资源。
- 第四个层次(Level 3)的 Web 服务使用 HATEOAS。在资源的表达中包含了链接信息。客户端可以根据链接来发现可以执行的动作。
简述
HATEOAS(Hypermedia as the engine of application state)是 REST 架构风格中最复杂的约束,也是构建成熟 REST 服务的核心。它的重要性在于客户端和服务器之间的解耦。
例子
分页
request请求,查询user,每页显示10条,从第10条开始显示(第二页)
/users?limit=10&offset=10
response
{ data: { xxxx }, meta: { _link: [ {rel: ‘self‘, href: ‘xxx/users?limit=10&offset=10‘}, {rel: ‘first‘, href: ‘xxx/users?limit=10&offset=0‘, title: ‘first page‘}, {rel: ‘last‘, href: ‘xxx/users?limit=10&offset=50‘, title: ‘last page‘}, {rel: ‘prev‘, href: ‘xxx/users?limit=10&offset=0‘, title: ‘prev page‘}, {rel: ‘next‘, href: ‘xxx/users?limit=10&offset=20‘, title: ‘next page‘} ] } }
_link
返回了5个资源
- rel: ‘self‘,资源本身
- rel: ‘first‘,第一页资源
- rel: ‘last‘,最后一页资源
- rel: ‘prev‘,上一页资源
- rel: ‘next‘,下一页资源
权限相关
如用户查询一个订单
普通用户
request
/orders/1
response
{ data: { xxx }, meta: { _link: [ {rel: ‘self‘, href: ‘xxx/orders/1‘}, {rel: ‘related‘, href: ‘xxx/orders/1/payment‘, title: ‘pay the order‘} ] } }
_link
返回两个资源
- rel: ‘self‘,资源本身
- rel: ‘related‘,与当前资源相关的资源,
/order/1/payment
用户可以使用此资源进行支付
权限用户
request
/orders/1
response
{ data: { xxx }, meta: { _link: [ {rel: ‘self‘, href: ‘xxx/orders/1‘}, {rel: ‘edit‘, href: ‘xxx/orders/1‘, title: ‘edit the order‘}, {rel: ‘delete‘, href: ‘xxx/orders/1‘, title: ‘delete the order‘} ] } }
此用户拥有修改与删除订单的权限,因此返回了3个资源
- rel: ‘self‘,资源本身
- rel: ‘edit‘,此用户可修改该资源
- rel: ‘delete‘,此用户可删除该资源
常用rel
rel | describe |
---|---|
self | 资源本身,每个资源表述都一个包含此关系 |
edit | 指向一个可以编辑当前资源的链接 |
delete | 指向一个可以删除当前资源的链接 |
item | 如果当前资源表示的是一个集合,则用来指向该集合中的单个资源 |
collection | 如果当前资源包含在某个集合中,则用来指向包含该资源的集合 |
related | 指向一个与当前资源相关的资源 |
first、last、prev、next | 分别用来指向第一个、最后一个、上一个和下一个资源 |
HATEOAS总结
由以上例子可以看出_link
就是以Hyperlink表述资源与资源之间的关系,这种方式使客户端与服务端能很好的分离开来,只要接口的定义不变,客户端与服务端就可以独立的开发和演变。
以上是关于RESTful API设计规范收集的主要内容,如果未能解决你的问题,请参考以下文章