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

原文链接

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