REST接口设计规范总结

时间 2019-11-19

标签 rest 接口设计规范总结栏目设计模式繁體版

原文原文链接

简介

Representational State Transfer 简称 REST 描述了一个架构样式的网络系统。REST 指的是一组架构约束条件和原则。知足这些约束条件和原则的应用程序或设计就是 RESTful。html

概念:git

资源（Resources） REST是”表现层状态转化”，其实它省略了主语。”表现层”其实指的是”资源”的”表现层”。那么什么是资源呢？就是咱们日常上网访问的一张图片、一个文档、一个视频等。这些资源咱们经过URI来定位，也就是一个URI表示一个资源。github
表现层（Representation）
资源是作一个具体的实体信息，他能够有多种的展示方式。而把实体展示出来就是表现层，例如一个txt文本信息，他能够输出成html、json、xml等格式，一个图片他能够jpg、png等方式展示，这个就是表现层的意思。
URI肯定一个资源，可是如何肯定它的具体表现形式呢？应该在HTTP请求的头信息中用Accept和Content-Type字段指定，这两个字段才是对”表现层”的描述。数据库
状态转化（State Transfer）访问一个网站，就表明了客户端和服务器的一个互动过程。在这个过程当中，确定涉及到数据和状态的变化。而HTTP协议是无状态的，那么这些状态确定保存在服务器端，因此若是客户端想要通知服务器端改变数据和状态的变化，确定要经过某种方式来通知它。json

URI格式规范

URI中尽可能使用连字符”-“代替下划线”_”的使用
URI中统一使用小写字母
URI中不要包含文件(脚本)的扩展名
资源的原型
文档(Document)

文档是资源的单一表现形式，能够理解为一个对象，或者数据库中的一条记录。在请求文档时，
要么返回文档对应的数据，要么会返回一个指向另一个资源(文档)的连接。
如下是几个基于文档定义的URI例子：
https://api.example.com/users/will
https://api.example.com/posts/1
https://api.example.com/posts/1/comments/1

集合(Collection)

集合能够理解为是资源的一个容器(目录)，咱们能够向里面添加资源(文档)。例如：
https://api.example.com/users
https://api.example.com/posts
https://api.example.com/posts/1/comments

仓库(Store)

仓库是客户端来管理的一个资源库，客户端能够向仓库中新增资源或者删除资源。
客户端也能够批量获取到某个仓库下的全部资源。仓库中的资源对外的访问不会提供单独URI的，
客户端在建立资源时候的URI除外。例如：
PUT /users/1234/favorites/posts/1  
上面的例子咱们能够理解为，咱们向一个id是1234的用户的仓库(收藏夹)中，
添加了一个id为1的post资源。通俗点儿说：就是用户收藏了一个本身喜好的id为1的文章。

控制器(Controller)

控制器资源模型，能够执行一个方法，支持参数输入，结果返回。 是为了除了标准操做:
增删改查(CRUD)之外的一些逻辑操做。控制器(方法)通常定义子URI中末尾，
而且不会有子资源(控制器)。例如：
向用户重发ID为245743的消息
POST /alerts/245743/resend  

发布ID为1的文章
POST /posts/1/publish

把动做转换成资源api

把动做转换成能够执行 CRUD 操做的资源， github 就是用了这种方法。

好比“喜欢”一个 gist，就增长一个 /gists/:id/star 子资源，
而后对其进行操做：“喜欢”使用 PUT /gists/:id/star，
“取消喜欢”使用 DELETE /gists/:id/star
或者使用 POST /gists/:id/unstar

另一个例子是 Fork，这也是一个动做，可是在 gist 下面增长 forks资源，
就能把动做变成 CRUD 兼容的：POST /gists/:id/forks 能够执行用户 fork 的动做。

URI命名规范

文档(Document)类型的资源用名词(短语)单数命名
集合(Collection)类型的资源用名词(短语)复数命名
仓库(Store)类型的资源用名词(短语)复数命名
控制器(Controller)类型的资源用动词(短语)命名
URI中有些字段能够是变量，在实际使用中能够按需替换

例如一个资源URI能够这样定义：
https://api.example.com/posts/{postId}/comments/{commentId}
postId,commentId 是变量(数字，字符串都类型均可以)。

CRUD的操做不要体如今URI中，HTTP协议中的操做符已经对CRUD作了映射。

CRUD是建立，读取，更新，删除这四个经典操做的简称  
例如删除的操做用REST规范执行的话，应该是这个样子：
DELETE /users/1234

如下是几个错误的示例：
GET /deleteUser?id=1234  
GET /deleteUser/1234  
DELETE /deleteUser/1234  
POST /users/1234/delete

URI的query字段

在REST中,query字段通常做为查询的参数补充，也能够帮助标示一个惟一的资源。但须要注意的是，
做为一个提供查询功能的URI，不管是否有query条件，咱们都应该保证结果的惟一性，
一个URI对应的返回数据是不该该被改变的(在资源没有修改的状况下)。
HTTP中的缓存也可能缓存查询结果。缓存

Query参数能够做为Collection或Store类型资源的过滤条件来使用例如：

GET /users //返回全部用户列表  
GET /users?role=admin //返回权限为admin的用户列表
GET /search/users?q={query}{&page,per_page,sort,order} //根据多条件查询用户

Query参数能够做为Collection或Store资源列表分页标示使用

若是是一个简单的列表操做，能够这样设计：
GET /users?pageSize=25&pageStartIndex=50  
若是是一个复杂的列表或查询操做的话，咱们能够为资源设计一个Collection，
由于复杂查询可能会涉及比较多的参数，建议使用Post的方式传入，例如这样：
POST /users/search

相关的分页信息还能够存放到 Link 头部，这样客户端能够直接获得诸以下一页、最后一页、上一页
等内容的 url 地址
Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="previous",
      <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 19

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请求

假设有两个客户端client#1/#2都向一个Store资源提交PUT请求，服务端是没法清楚的判断是要
insert仍是要update的，因此咱们要在header中加入条件标示if-Match，If-Unmodified-Since
来明确是本次调用API的意图。例如：

client#1第一次向服务端发起一个请求 PUT /objects/2113 此时2113资源还不存在，那服务端会
认为本次请求是一个insert操做，完成后，会返回 201 (“Created”)

client#2再一次向服务端发起同一个请求 PUT /objects/2113 时，因2113资源已存在，服务端会
返回 409 (“Conflict”)

为了能让client#2的请求成功，或者说咱们要清楚的代表本次操做是一次update操做，咱们必须在
header中加入一些条件标示，例如 if-Match。咱们须要给出资源的ETag(if-Match:Etag)，来表
明咱们但愿更新资源的版本，若是服务端版本一致，会返回200 (“OK”) 或者 204 (“No Content”)。
若是服务端发现指定的版本与当前资源版本不一致，会返回 412 (“Precondition Failed”)

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 设计为子域名，
好比 api.github.com/v3；也能够简单地把版… example.com/api/v1。
另外一种作法是，将版本号放在HTTP头信息中。服务器

限流 rate limit

若是对访问的次数不加控制，极可能会形成 API 被滥用，甚至被 DDos 攻击。根据使用者不一样的身份对其进行限流，能够防止这些状况，减小服务器的压力。restful

对用户的请求限流以后，要有方法告诉用户它的请求使用状况，Github API 使用的三个相关的头部：网络

X-RateLimit-Limit: 用户每一个小时容许发送请求的最大值
X-RateLimit-Remaining：当前时间窗口剩下的可用请求数目
X-RateLimit-Rest: 时间窗口重置的时候，到这个时间点可用的请求数量就会变成 X-RateLimit-Limit 的值

对于超过流量的请求，能够返回 429 Too many requests 状态码，并附带错误信息。