REST接口设计规范总结
简介
Representational State Transfer 简称 REST 描述了一个架构样式的网络系统。REST 指的是
一组架构约束条件和原则。满足这些约束条件和原则的应用程序或设计就是 RESTful。
概念:
-
资源(Resources) REST是”表现层状态转化”,其实它省略了主语。”表现层”其实指的是”资源”的”表现层”。
那么什么是资源呢?就是我们平常上网访问的一张图片、一个文档、一个视频等。这些资源我们通过URI来定位,也就是一个URI表示一个资源。 -
表现层(Representation)
资源是做一个具体的实体信息,他可以有多种的展现方式。而把实体展现出来就是表现层,例如一个txt文本信息,他可以输出成html、json、xml等格式,一个图片他可以jpg、png等方式展现,这个就是表现层的意思。
URI确定一个资源,但是如何确定它的具体表现形式呢?应该在HTTP请求的头信息中用Accept和Content-Type字段指定,这两个字段才是对”表现层”的描述。 -
状态转化(State Transfer)
访问一个网站,就代表了客户端和服务器的一个互动过程。在这个过程中,肯定涉及到数据和状态的变化。而HTTP协议是无状态的,那么这些状态肯定保存在服务器端,所以如果客户端想要通知服务器端改变数据和状态的变化,肯定要通过某种方式来通知它。
URI格式规范
-
URI中尽量使用连字符”-“代替下划线”_”的使用
-
URI中统一使用小写字母
-
URI中不要包含文件(脚本)的扩展名
资源的原型
-
文档(Document)
1 |
文档是资源的单一表现形式,可以理解为一个对象,或者数据库中的一条记录。在请求文档时, |
-
集合(Collection)
1 |
集合可以理解为是资源的一个容器(目录),我们可以向里面添加资源(文档)。例如: |
-
仓库(Store)
1 |
仓库是客户端来管理的一个资源库,客户端可以向仓库中新增资源或者删除资源。 |
-
控制器(Controller)
1 |
控制器资源模型,可以执行一个方法,支持参数输入,结果返回。 是为了除了标准操作: |
把动作转换成资源
1 |
把动作转换成可以执行 CRUD 操作的资源, github 就是用了这种方法。 |
URI命名规范
-
文档(Document)类型的资源用名词(短语)单数命名
-
集合(Collection)类型的资源用名词(短语)复数命名
-
仓库(Store)类型的资源用名词(短语)复数命名
-
控制器(Controller)类型的资源用动词(短语)命名
-
URI中有些字段可以是变量,在实际使用中可以按需替换
1 |
例如一个资源URI可以这样定义: |
-
CRUD的操作不要体现在URI中,HTTP协议中的操作符已经对CRUD做了映射。
1 |
CRUD是创建,读取,更新,删除这四个经典操作的简称 |
URI的query字段
在REST中,query字段一般作为查询的参数补充,也可以帮助标示一个唯一的资源。但需要注意的是,
作为一个提供查询功能的URI,无论是否有query条件,我们都应该保证结果的唯一性,
一个URI对应的返回数据是不应该被改变的(在资源没有修改的情况下)。
HTTP中的缓存也可能缓存查询结果。
-
Query参数可以作为Collection或Store类型资源的过滤条件来使用 例如:
1 |
GET /users //返回所有用户列表 |
-
Query参数可以作为Collection或Store资源列表分页标示使用
1 |
如果是一个简单的列表操作,可以这样设计: |
HTTP请求方法的使用
-
GET方法用来获取资源
-
PUT方法可用来新增/更新Store类型的资源
-
PUT方法可用来更新一个资源的全部属性,使用时传递所有属性的值,即使有的值没有改变
-
PATCH方法更新资源的部分属性。因为 PATCH 比较新,而且规范比较复杂,所以真正实现的比较少,
一般都是用 POST 替代 -
POST方法可用来创建一个资源
-
POST方法可用来触发执行一个Controller类型资源
-
DELETE方法用于删除资源
HTTP响应状态码的使用
-
200 (“OK”) 用于一般性的成功返回
-
200 (“OK”) 不可用于请求错误返回
-
201 (“Created”) 资源被创建
-
202 (“Accepted”) 用于Controller控制类资源异步处理的返回,仅表示请求已经收到。
对于耗时比较久的处理,一般用异步处理来完成 -
204 (“No Content”) 此状态可能会出现在PUT、POST、DELETE的请求中,一般表示资源存在,
但消息体中不会返回任何资源相关的状态或信息。 -
301 (“Moved Permanently”) 资源的URI被转移,需要使用新的URI访问
-
302 (“Found”) 不推荐使用,此代码在HTTP1.1协议中被303/307替代。
我们目前对302的使用和最初HTTP1.0定义的语意是有出入的,应该只有在GET/HEAD方法下,
客户端才能根据Location执行自动跳转,而我们目前的客户端基本上是不会判断原请求方法的,
无条件的执行临时重定向 -
303 (“See Other”) 返回一个资源地址URI的引用,但不强制要求客户端获取该地址的状态(访问该地址)
-
304 (“Not Modified”) 有一些类似于204状态,服务器端的资源与客户端最近访问的资源版本一致,
并无修改,不返回资源消息体。可以用来降低服务端的压力 -
307 (“Temporary Redirect”) 目前URI不能提供当前请求的服务,临时性重定向到另外一个URI。
在HTTP1.1中307是用来替代早期HTTP1.0中使用不当的302 -
400 (“Bad Request”) 用于客户端一般性错误返回, 在其它4xx错误以外的错误,也可以使用400,
具体错误信息可以放在body中 -
401 (“Unauthorized”) 在访问一个需要验证的资源时,验证错误
-
403 (“Forbidden”) 一般用于非验证性资源访问被禁止,例如对于某些客户端只开放部分API的访问权限,
而另外一些API可能无法访问时,可以给予403状态 -
404 (“Not Found”) 找不到URI对应的资源
-
405 (“Method Not Allowed”) HTTP的方法不支持,例如某些只读资源,可能不支持POST/DELETE。
但405的响应header中必须声明该URI所支持的方法 -
406 (“Not Acceptable”) 客户端所请求的资源数据格式类型不被支持,
例如客户端请求数据格式为application/xml,但服务器端只支持application/json -
409 (“Conflict”) 资源状态冲突,例如客户端尝试删除一个非空的Store资源
-
412 (“Precondition Failed”) 用于有条件的操作不被满足时
-
415 (“Unsupported Media Type”) 客户所支持的数据类型,服务端无法满足
-
429 (“Too Many Requests”) 客户端在规定的时间里发送了太多请求,在进行限流的时候会用到
-
500 (“Internal Server Error”) 服务器端的接口错误,此错误于客户端无关
HTTP Headers
-
Content-Type 标示body的数据格式
-
Content-Length body 数据体的大小,客户端可以根据此标示检验读取到的数据是否完整,
也可以通过Header判断是否需要下载可能较大的数据体 -
Last-Modified 用于服务器端的响应,是一个资源最后被修改的时间戳,客户端(缓存)可以根据
此信息判断是否需要重新获取该资源 -
ETag 服务器端资源版本的标示,客户端(缓存)可以根据此信息判断是否需要重新获取该资源,
需要注意的是,ETag如果通过服务器随机生成,可能会存在多个主机对同一个资源产生不同ETag的问题 -
Store类型的资源要支持有条件的PUT请求
1 |
假设有两个客户端client#1/#2都向一个Store资源提交PUT请求,服务端是无法清楚的判断是要 |
-
Location 在响应header中使用,一般为客户端感兴趣的资源URI,例如在成功创建一个资源后,我们
可以把新的资源URI放在Location中,如果是一个异步创建资源的请求,接口在响应202 (“Accepted”)
的同时可以给予客户端一个异步状态查询的地址 -
Cache-Control, Expires, Date 通过缓存机制提升接口响应性能,同时根据实际需要也可以禁止
客户端对接口请求做缓存。对于REST接口来说,如果某些接口实时性要求不高的情况下,我们可以使
用max-age来指定一个小的缓存时间,这样对客户端和服务器端双方都是有利的。一般来说只对GET
方法且返回200的情况下使用缓存,在某些情况下我们也可以对返回3xx或者4xx的情况下做缓存,可
以防范错误访问带来的负载。 -
我们可以自定义一些头信息,作为客户端和服务器间的通信使用,但不能改变HTTP方法的性质。自
定义头尽量简单明了,不要用body中的信息对其作补充说明。
API 地址和版本
在 url 中指定 API 的版本是个很好地做法。如果 API 变化比较大,可以把 API 设计为子域名,
比如 https://api.github.com/v3;也可以简单地把版本放在路径中,比如 https://example.com/api/v1。
另一种做法是,将版本号放在HTTP头信息中。
限流 rate limit
如果对访问的次数不加控制,很可能会造成 API 被滥用,甚至被 DDos 攻击。根据使用者不同的身
份对其进行限流,可以防止这些情况,减少服务器的压力。
对用户的请求限流之后,要有方法告诉用户它的请求使用情况,Github API 使用的三个相关的头部:
-
X-RateLimit-Limit: 用户每个小时允许发送请求的最大值
-
X-RateLimit-Remaining:当前时间窗口剩下的可用请求数目
-
X-RateLimit-Rest: 时间窗口重置的时候,到这个时间点可用的请求数量就会变成 X-RateLimit-Limit 的值
对于超过流量的请求,可以返回 429 Too many requests 状态码,并附带错误信息。
参考文档
-
http://cizixs.com/2016/12/12/restful-api-design-guide
-
http://wangwei.info/about-rest-api/
-
http://www.ruanyifeng.com/blog/2011/09/restful.html
-
http://www.ruanyifeng.com/blog/2014/05/restful_api.html
-
https://zh.wikipedia.org/wiki/REST
-
https://developer.github.com/v3