RESTful API 设计实践

RESTful 的核心思想就是，客户端发出的数据操作指令都是 动词+宾语 的结构。比如， GET /articles 这个命令，GET 是动词， /articles 是宾语。动词通常就是五种 HTTP 方法，对应 CRUD 操作。

• GET：读取（Read）
• POST：新建（Create）
• PUT：更新（Update）
• PATCH：更新（Update），通常是部分更新
• DELETE：删除（Delete）

有些客户端只能使用 GET 和 POST 这两种 HTTP 方法。这些必要的时候可以使用 POST 动词来覆盖其它三种方法。例如，X-HTTP-Method-Override 指定本次请求的方法是 PUT， 而不是 POST。

POST /api/article/4 HTTP/1.1
X-HTTP-Method-Override: PUT

宾语就是 API 的 URL，是 HTTP 动词作用的对象， 宾语必须名词 。比如， /articles 这个 URL 就是正确的，而下面的 URL 不是名词，所以都是错误的。

/getAllArticles
/createNewArticle
/deleteAllYesterdayArticles

URL 作为宾语的单复数形式没有统一的规定。常见的操作是读取一个集合用的是复数。

GET /articles

操作单个元素使用单数形式。

GET /articles/2

常见的情况是，资源需要多级分类，因此很容易写出多级的 URL，比如获取某个作者的某一 类文章。

GET /authors/12/categories/2

这种 URL 不利于扩展，语义也不明确，往往要想一会，才能明白含义。更好的做法是，除 了第一级，其他级别都用查询字符串表达。

GET /authors/12?categories=2

下面是另一个例子，查询已发布的文章。你可能会设计成下面的 URL。

GET /articles/published

查询字符串的写法明显更好。

GET /articles?published=true

总结出来一句话， 使用分类查询最好是用参数的方式来修饰 。

客户端的每一次请求，服务器都必须给出回应。回应包括 HTTP 状态码和数据两部分。 HTTP 状态码就是一个三位数，分成五个类别。

200 状态码表示操作成功，但是不同的方法可以返回更精确的状态码。

• GET: 200 OK
• POST: 201 Created
• PUT: 200 OK
• PATCH: 200 OK
• DELETE: 204 No Content

上面代码中，POST 返回 201 状态码，表示生成了新的资源；DELETE 返回 204 状态码， 表示资源已经不存在。此外，202 Accepted 状态码表示服务器已经收到请求，但还未进 行处理，会在未来再处理，通常用于异步操作。下面是一个例子。

HTTP/1.1 202 Accepted
{
  "task": {
     "href": "/api/company/job-management/jobs/2130040",
     "id": "2130040"
  }
}

API 用不到 301 状态码（永久重定向）和 302 状态码（暂时重定向，307 也是这个含 义），因为它们可以由应用级别返回，浏览器会直接跳转，API 级别可以不考虑这两种 情况。API 用到的 3xx 状态码，主要是 303 See Other，表示参考另一个 URL。它与 302 和 307 的含义一样，也是"暂时重定向"，区别在于 302 和 307 用于 GET 请求， 而 303 用于 POST、PUT 和 DELETE 请求。收到 303 以后，浏览器不会自动跳转，而会 让用户自己决定下一步怎么办。下面是一个例子。

HTTP/1.1 303 See Other
Location: /api/articles/12345

4xx 状态码表示客户端错误，主要有下面几种。

5xx 状态码表示服务端错误。一般来说，API 不会向用户透露服务器的详细信息，所以 只要两个状态码就够了。

API 返回的数据格式，不应该是纯文本，而应该是一个 JSON 对象，因为这样才能返回 标准的结构化数据。所以，服务器回应的 HTTP 头的 Content-Type 属性要设为 application/json 。客户端请求时，也要明确告诉服务器，可以接受 JSON 格式，即请 求的 HTTP 头的 ACCEPT 属性也要设成 application/json 。下面是一个例子。

GET /article/2 HTTP/1.1
Accept: application/json

有一种不恰当的做法是，即使发生错误，也返回 200 状态码，把错误信息放在数据体里 面，就像下面这样。

HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "failure",
  "data": {
    "error": "Expected at least two items in list."
  }
}

上面代码中，解析数据体以后，才能得知操作失败。这张做法实际上取消了状态码，这 是完全不可取的。正确的做法是，状态码反映发生的错误，具体的错误信息放在数据体 里面返回。下面是一个例子。

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
  "error": "Invalid payoad.",
  "detail": {
    "surname": "This field is required."
  }
}

API 的使用者未必知道，URL 是怎么设计的。一个解决方法就是，在回应中，给出相关 链接，便于下一步操作。这样的话，用户只要记住一个 URL，就可以发现其他的 URL。 这种方法叫做 HATEOAS。举例来说，GitHub 的 API 都在 https://api.github.com/ 这个域名。访问它，就可以得到其他 URL。

{
  "current_user_url": "https://api.github.com/user",
  "current_user_authorizations_html_url": "https://github.com/settings/connections/applications{/client_id}",
  "authorizations_url": "https://api.github.com/authorizations",
  "code_search_url": "https://api.github.com/search/code?q={query}{&page,per_page,sort,order}",
  "commit_search_url": "https://api.github.com/search/commits?q={query}{&page,per_page,sort,order}",
  "emails_url": "https://api.github.com/user/emails",
  "emojis_url": "https://api.github.com/emojis",
  "events_url": "https://api.github.com/events",
  "feeds_url": "https://api.github.com/feeds",
  "followers_url": "https://api.github.com/user/followers",
  "following_url": "https://api.github.com/user/following{/target}",
  "gists_url": "https://api.github.com/gists{/gist_id}",
  "hub_url": "https://api.github.com/hub",
  "issue_search_url": "https://api.github.com/search/issues?q={query}{&page,per_page,sort,order}",
  "issues_url": "https://api.github.com/issues",
  "keys_url": "https://api.github.com/user/keys",
  "notifications_url": "https://api.github.com/notifications",
  "organization_repositories_url": "https://api.github.com/orgs/{org}/repos{?type,page,per_page,sort}",
  "organization_url": "https://api.github.com/orgs/{org}",
  "public_gists_url": "https://api.github.com/gists/public",
  "rate_limit_url": "https://api.github.com/rate_limit",
  "repository_url": "https://api.github.com/repos/{owner}/{repo}",
  "repository_search_url": "https://api.github.com/search/repositories?q={query}{&page,per_page,sort,order}",
  "current_user_repositories_url": "https://api.github.com/user/repos{?type,page,per_page,sort}",
  "starred_url": "https://api.github.com/user/starred{/owner}{/repo}",
  "starred_gists_url": "https://api.github.com/gists/starred",
  "team_url": "https://api.github.com/teams",
  "user_url": "https://api.github.com/users/{user}",
  "user_organizations_url": "https://api.github.com/user/orgs",
  "user_repositories_url": "https://api.github.com/users/{user}/repos{?type,page,per_page,sort}",
  "user_search_url": "https://api.github.com/search/users?q={query}{&page,per_page,sort,order}"
}

上面的回应中，挑一个 URL 访问，又可以得到别的 URL。对于用户来说，不需要记住 URL 设计，只要从 api.github.com 一步步查找就可以了。HATEOAS 的格式没有统一规定， 上面例子中，GitHub 将它们与其他属性放在一起。更好的做法应该是，将相关链接与其 他属性分开。

HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "In progress",
  "links": {[
    { "rel":"cancel", "method": "delete", "href":"/api/status/12345" } ,
    { "rel":"edit", "method": "put", "href":"/api/status/12345" }
  ]}
}