Restful API 设计规范
使用的名词而不是动词
不应该使用动词:
/getAllResources/createNewResources/deleteAllResources
GET方法和查询参数不能改变资源状态:
如果要改变资源的状态,使用PUT、POST、DELETE。下面是错误的用GET方法来修改user的状态:
GET /users/711?activate
GET /users/711/activate
Rest的核心原则是将你的API拆分为逻辑上的资源。这些资源通过HTTP被操作(GET,POST,PUT,DELETE)
我们定义资源ticket、user、group:
GET /tickets # 获取ticket列表
GET /tickets/12 # 查看某个具体的ticket
POST /tickets # 新建一个ticket
PUT /tickets/12 #新建ticket 12
DELETE /tickets/12 # 删除ticket 12
只需要一个endpoint:/tickets,再也没有其他什么命名规则和url规则了。
一个可以遵循的规则是:虽然看起来使用复数来描述某一个资源看起来特别扭,但是统一所有的endpoint,使用复数使得你的URL更加规整。这让API使用者更加容易理解,对开发者来说也更容易实现。
处理关联:
GET /tickets/12/messages # 获取ticket 12的message列表
GET /tickets/12/messages/5 #获取ticket 12的message 5
POST /tickets/12/messages 创建ticket 12的一个message
PUT /tickets/12/messages/5 更新ticket 12的message 5
DELETE /tickets/12/messages/5 删除ticket 12的message 5
避免层级过深的URI
/
在url中表达层级,用于按实体关联关系进行对象导航,一般根据id导航。
过深的导航容易导致url膨胀,不易维护,如 GET /zoos/1/areas/3/animals/4
,尽量使用查询参数代替路劲中的实体导航,如GET /animals?zoo=1&area=3
。
结果过滤,排序,搜索
url最好越简短越好,对结果过滤、排序、搜索相关的功能都应该通过参数实现。
过滤:例如你想限制GET /tickets
的返回结果:只返回那些open状态的ticket, GET /tickets?state=open
这里的state就是过滤参数。
排序:和过滤一样,一个好的排序参数应该能够描述排序规则,而不和业务相关。复杂的排序规则应该通过组合实现。排序参数通过 ,
分隔,排序参数前加 -
表示降序排列。
GET /tickets?sort=-priority #获取按优先级降序排列的ticket列表
GET /tickets?sort=-priority,created_at #获取按优先级降序排列的ticket列表,在同一个优先级内,先创建的ticket排列在前面。
搜索:有些时候简单的排序是不够的。我们可以使用搜索技术来实现
GET /tickets?q=return&state=open&sort=-priority,create_at # 获取优先级最高且打开状态的ticket,而且包含单词return的ticket列表。
限制API返回值的域
有时候API使用者不需要所有的结果,在进行横向限制的同时(例如值返回API结果的前十个),还应该可以进行纵向限制,并且这个功能能有效的提高网络带宽使用率和速度。可以使用fields查询参数来限制返回的域例如:
GET /tickets?fields=id,subject,customer_name,updated_at&state=open&sort=-updated_at
Response不要包装
response 的 body直接就是数据,不要做多余的包装。错误实例:
{
"success":true,
"data":{"id":1, "name":"xiaotuan"}
}
更新和创建操作应该返回资源
在POST操作以后,返回201created 状态码,并且包含一个指向新资源的url作为返回头。
命名方式
是蛇形命名还是驼峰命名?如果使用json那么最好的应该是遵守JavaScript的命名方法-驼峰命名法。Java、C# 使用驼峰,python、ruby使用蛇形。
默认使用pretty print格式,开启gzip
开启pretty print返回结果会更加友好易读,而且额外的传输也可以忽略不计。如果忘了使用gzip那么传输效率将会大大减少,损失大大增加。
GitHub v3S实践经验
1.Current Version
通过Accept字段来区分版本号,而不是在url中嵌入版本号: Accept: application/vnd.github.v3+json
2.Schema
Summary Representation
当你请求获取某一资源的列表时,响应仅返回资源的属性子集。有些属性对API来说代价是非常高的,出于性能的考虑,会排除这些属性。要获取这些属性,请求"detailed" representation。
Example:当你获取仓库的列表时,你获得的是每个仓库的summary representation。
GET /orgs/octokit/repos
Detailed Representation
当你获取一个单独的资源时,响应会返回这个资源的所有属性。
Example:当你获取一个单独的仓库,你会获得这个仓库的detailed representation。
GET /repos/octokit/octokit.rb
3.Parameters
许多API都带有可选参数。对于GET请求,任何不作为路径构成部分的参数都可以通过HTTP查询参数传入。
GET https://api.github.com/repos/vmg/redcarpet/issues?state=closed
在这个例子中,'vmg' 和 'redcarpet' 作为 :owner 和 :repo 的参数,而 :state 作为查询参数。
对于POST、PATCH、PUT和DELETE的请求,不包含在URL中的参数需要编码成JSON传递,且 Content-Type为 'application/json'。
Root Endpoint
你可以对根节点GET请求,获取根节点下的所有API分类。
Client Errors
有三种可能的客户端错误,在接收到请求体时:
1 发送非法JSON会返回 400 Bad Request.
HTTP/1.1 400 Bad Request
Content-Length: 35
{"message":"Problems parsing JSON"}
2 发送错误类型的JSON值会返回 400 Bad Request.
HTTP/1.1 400 Bad Request
Content-Length: 40
{"message":"Body should be a JSON object"}
3 发送无效的值会返回 422 Unprocessable Entity.
HTTP/1.1 422 Unprocessable Entity
Content-Length: 149
{
"message": "Validation Failed",
"errors": [
{
"resource": "Issue",
"field": "title",
"code": "missing_field"
}
]
}
我们可以告诉发生了什么错误,下面是一些可能的验证错误码:
Error Name | Description |
---|---|
missing | 资源不存在 |
missing_field | 资源必需的域没有被设置 |
invalid | 域的格式非法 |
already_exists | 另一个资源的域的值和此处的相同,这会发生在资源有唯一的键的时候 |
HTTP Redirects
API v3在合适的地方使用HTTP重定向。客户端应该假设任何请求都会导致重定向。重定向在响应头中有一个 Location
的域,此域包含了资源的真实位置。
HTTP Verbs
API v3力争使用正确的HTTP动词来表示每次请求。
Verb | Description |
---|---|
HEAD | 对任何资源仅请求头信息 |
GET | 获取资源 |
POST | 创建资源 |
PATCH | 使用部分的JSON数据更新资源 |
PUT | 取代资源或资源集合 |
DELETE | 删除资源 |
Hypermedia
很多资源有一个或者更多的 *_url
属性指向其他资源。这意味着服务端提供明确的URL,这样客户端就不必要自己构造URL了。
Pagination
请求资源列表时会进行分页,默认每页30个。当你请求后续页的时候可以使用 ?page
参数。对于某些资源,你可以通过参数 ?per_page
自定义每页的大小。
curl 'https://api.github.com/user/repos?page=2&per_page=100'
需要注意的一点是,页码是从1开始的,当省略参数 ?page
时,会返回首页。
Basics of Pagination
关于分页的其他相关信息在响应的头信息的 Link
里提供。比如,去请求一个搜索的API,查找Mozilla的项目中哪些包含词汇addClass :
curl -I "https://api.github.com/search/code?q=addClass+user:mozilla"
头信息中Link字段如下:
Link: <https://api.github.com/search/code?q=addClass+user%3Amozilla&page=2>; rel="next", <https://api.github.com/search/code?q=addClass+user%3Amozilla&page=34>; rel="last"
rel="next"
表示下一页是 page=2
。也就是说,默认情况下所有的分页请求都是从首页开始。rel="last"
提供更多信息,表示最后一页是34。即我们还有33页的信息包含addClass。
总之,我们应该依赖于Link提供的信息,而不要尝试自己去猜或者构造URL。
Navigating through the pages
既然已经知道会接收多少页面,我们可以通过页面导航来消费结果。我们可以通过传递一个page
参数,例如跳到14页:
curl -I "https://api.github.com/search/code?q=addClass+user:mozilla&page=14"
这是头信息中Link字段:
Link: <https://api.github.com/search/code?q=addClass+user%3Amozilla&page=15>; rel="next",
<https://api.github.com/search/code?q=addClass+user%3Amozilla&page=34>; rel="last",
<https://api.github.com/search/code?q=addClass+user%3Amozilla&page=1>; rel="first",
<https://api.github.com/search/code?q=addClass+user%3Amozilla&page=13>; rel="prev"
我们会获得更多的信息,rel="first"
表示首页,rel="prev"
表示前一页的页码。通过这些信息,我们可以构造一个UI界面让用户在first、previous、next、last之间进行跳转。
Rate Limiting
对于认证的请求,可以每小时最多请求5000次。对于没有认证的请求,限制在每小时60次请求。
检查返回的HTTP头,可以看到当前的速率限制:
curl -i https://api.github.com/users/whatever
HTTP/1.1 200 OK
Server: GitHub.com
Date: Thu, 27 Oct 2016 03:05:42 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 1219
Status: 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 48
X-RateLimit-Reset: 1477540017
header头信息告诉你当前的速率限制状态:
Header Name | Description |
---|---|
X-RateLimit-Limit | 当前用户被允许的每小时请求数 |
X-RateLimit-Remaining | 在当前发送窗口内还可以发送的请求数 |
X-RateLimit-Reset | 按当前速率发送后,发送窗口重置的时间 |
一旦你超过了发送速率限制,你会收到一个错误响应:
HTTP/1.1 403 Forbidden
Date: Tue, 20 Aug 2013 14:50:41 GMT
Status: 403 Forbidden
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1377013266
{
"message": "API rate limit exceeded for xxx.xxx.xxx.xxx. (But here's the good news: Authenticated requests get a higher rate limit. Check out the documentation for more details.)",
"documentation_url": "https://developer.github.com/v3/#rate-limiting"
}
User Agent Required
所有的API请求必须包含一个有效的 User-Agent
头。请求头不包含User-Agent
的请求会被拒绝。
Conditional requests
大多数响应都会返回一个 ETag
头。很多响应也会返回一个 Last-Modified
头。你可以使用这些头信息对这些资源进行后续请求,分别使用 If-None-Match
和 If-Modified-Since
头。如果资源没有发生改变,服务器端会返回 304 Not Modified
。
Enchant REST API 实践经验
Requests
Limited HTTP Clients
如果你使用的HTTP客户端不支持PUT、PATCH、DELETE方法,发送一个POST请求,头信息里包含X-HTTP-Method-Override字段,它的值是实际需要的动词。
$ curl -u email:password https://site.enchant.com/api/v1/users/543abc \
-X POST \
-H "X-HTTP-Method-Override: DELETE"
Rate Limiting
所有响应的头部包含描述当前限流状态的字段:
Rate-Limit-Limit: 100
Rate-Limit-Remaining: 99
Rate-Limit-Used: 1
Rate-Limit-Reset: 20
Rate-Limit-Limit
- 当前时间段内允许的总的请求数Rate-Limit-Remaining
- 当前时间段内还剩余的请求数Rate-Limit-Used
- 本次所使用的请求数Rate-Limit-Reset
- 重置所需秒数
如果速率限制被打破,API会返回 429 Too Many Requests
的状态码。在这种情况下,你的应用不应该再发送任何请求直到 Rate-Limit-Reset
所规定的时间过去。
Field Filtering
你可以自己限制响应返回的域。只需要你传递一个 fields
参数,用逗号分隔所需要的域,比如:
GET /api/v1/users?fields=id,first_name
Counting
所有返回一个集合的URL,都会提供count统计所有结果的个数。要获取count值需要加一个 count=true
的参数。count会在消息头中的Total-Count
字段中返回。
GET /api/v1/tickets?count=true
200 OK
Total-Count: 135
Rate-Limit-Limit: 100
Rate-Limit-Remaining: 98
Rate-Limit-Used: 2
Rate-Limit-Reset: 20
Content-Type: application/json
[
... results ...
]
count表示所有现存结果的数量,而不是此次响应返回的结果的数量。
Enveloping
如果你的HTTP客户端难以读取状态码和头信息,我们可以将所有都打包进响应消息体中。我们只需要传递参数 envelope=true
,而API会始终返回200的HTTP状态码。真正的状态码、头信息和响应都在消息体中。
GET /api/v1/users/does-not-exist?envelope=true
200 OK
{
"status": 404,
"headers": {
"Rate-Limit-Limit": 100,
"Rate-Limit-Remaining": 50,
"Rate-Limit-Used": 0,
"Rate-Limit-Reset": 25
},
"response": {
"message": "Not Found"
}
}
其他如 分页、排序等,enchant的设计规范和GitHub v3大致相同,不在赘述。
**粗体** _斜体_ [链接](http://example.com) `代码` - 列表 > 引用
。你还可以使用@
来通知其他用户。