Restful API 设计规范实战

扑火的蛾

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-MatchIf-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大致相同,不在赘述。

原文链接

https://segmentfault.com/a/11...

阅读 16.8k

空中漫步
看到什么写什么

与世界分享你的装逼经验。

269 声望
29 粉丝
0 条评论

与世界分享你的装逼经验。

269 声望
29 粉丝
文章目录
宣传栏