服务计算——设计一个博客网站的 API

概要

所有 API 访问都是通过 HTTPS 进行的，并且可以通过访问 https://api.blog.com。所有数据都以 JSON 的形式发送和接收。

curl -i https://api.blog.com/users/lzz
HTTP/1.1 200 OK
Server: nginx
Date: Wed, 20 Nov 2019 23:33:14 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Status: 200 OK
ETag: "a00049ba79152d03380c34652f2cb612"
X-GitHub-Media-Type: blog.v3
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4987
X-RateLimit-Reset: 1350085394
Content-Length: 5
Cache-Control: max-age=0, private, must-revalidate
X-Content-Type-Options: nosniff

包含空白字段，null而不是将其省略。

所有时间戳以 ISO 8601 格式返回：YYYY-MM-DDTHH:MM:SSZ

摘要表示

当获取资源列表时，响应包括该资源的属性子集。这是资源的“摘要”表示。

示例：获得所有博客时，将获得每个博客的摘要表示。在这里，获取用户 lzz 所有博客的摘要表示：

GET /user/lzz/blogs

详细表示

当获取单个资源时，响应通常包括该资源的所有属性。这是资源的“详细”表示。

示例：获得单个博客时，将获得单个博客的详细表示。在这里，获取用户 lzz 博客123 的详细表示：

GET /user/lzz/blog/123

认证方式

有两种方法可以通过 Blog API 进行身份验证。需要身份验证的请求在某些地方将返回 404 Not Found，而不是 403 Forbidden。这是为了防止私有存储库意外泄露给未经授权的用户。

基本认证

curl -u "username" https://api.blog.com

登录限制失败

使用无效的凭据进行身份验证将返回 401 Unauthorized：

curl -i https://api.blog.com -u foo:bar
HTTP/1.1 401 Unauthorized
{
  "message": "Bad credentials",
  "documentation_url": "https://developer.blog.com/v3"
}

在短时间内检测到多个具有无效凭据的请求后，API 会临时拒绝该用户的所有身份验证尝试（包括具有有效凭据的请求）403 Forbidden：

curl -i https://api.blog.com -u valid_username:valid_password
HTTP/1.1 403 Forbidden
{
  "message": "Maximum number of login attempts exceeded. Please try again later.",
  "documentation_url": "https://developer.blog.com/v3"
}

参数

许多 API 方法采用可选参数。对于 GET 请求，任何未在路径中指定为段的参数都可以作为 HTTP 查询字符串参数传递：

curl -i“ https://api.blog.com/blogs/lzz/123/issues?state=closed”

在此示例中，在查询字符串中传递路径时，lzz 作为 user 的参数，123 作为 blog 的参数，:state 作为传递路径的参数。

为 POST，PATCH，PUT 和 DELETE 的要求，不包含在 URL 参数应当被编码为 JSON 与“应用/JSON”的内容类型：

curl -i -u username -d '{"scopes":["public_blog"]}' https://api.blog.com/authorizations

根端点

使用 GET 向根端点发出请求，以获取 REST API 支持的所有端点类别：

curl https://api.blog.com

客户错误

接收请求正文的 API 调用上可能存在三种类型的客户端错误：

• 发送无效的 JSON 将导致 400 Bad Request 响应。

HTTP/1.1 400 Bad Request
Content-Length: 35

{"message":"Problems parsing JSON"}

• 发送错误类型的 JSON 将导致 400 Bad Request 响应。

HTTP/1.1 400 Bad Request
Content-Length: 40

{"message":"Body should be a JSON object"}

• 发送无效的字段将导致 422 Unprocessable Entity 响应。

HTTP/1.1 422 Unprocessable Entity
Content-Length: 149

{
  "message": "Validation Failed",
  "errors": [
    {
      "resource": "Issue",
      "field": "title",
      "code": "missing_field"
    }
  ]
}

所有错误对象都具有资源和字段属性，以便客户端可以知道问题所在。还有一个错误代码，说明该字段出了什么问题。这些是可能的验证错误代码：

错误名称	描述
missing	这意味着资源不存在。
missing_field	这意味着尚未设置资源上的必填字段。
invalid	这意味着字段格式无效。该资源的文档应该能够提供更多具体信息。
already_exists	这意味着另一个资源具有与此字段相同的值。在必须具有某些唯一键（例如标签名称）的资源中可能会发生这种情况。

资源还可以发送自定义的验证错误。自定义错误将始终具有 message 描述错误的字段，并且大多数错误还将包括 documentation_url 指向一些可能有助于解决错误的内容的字段。

HTTP 重定向

API 在适当的地方使用 HTTP 重定向。客户应假定任何请求都可能导致重定向。接收 HTTP 重定向不是错误，客户端应遵循该重定向。重定向响应将具有一个 Location 标头字段，其中包含客户端应向其重复请求的资源的 URI。

状态码	描述
301	永久重定向。用于发出请求的 URI 已被 Location 标头字段中指定的 URI 取代。对此资源的此请求以及所有将来的请求都应定向到新 URI。
302，307	临时重定向。应按 Location 标头字段中指定的 URI 逐字重复请求，但客户端应继续将原始 URI 用于以后的请求。

HTTP 动词

API 尽可能在每个动作中使用适当的 HTTP 动词。

动词	描述
HEAD	可以针对任何资源发出以仅获取 HTTP 标头信息。
GET	用于检索资源。
POST	用于创建资源。
PATCH	用于通过部分 JSON 数据更新资源。例如，问题资源具有 title 和 body 属性。PATCH 请求可以接受一个或多个属性以更新资源。PATCH 是一个相对较新且不常见的 HTTP 动词，因此资源端点也接受 POST 请求。
PUT	用于替换资源或集合。对于 PUT 没有 body 属性的请求，请确保将 Content-Length 标头设置为零。
DELETE	用于删除资源。

超媒体

所有资源都可以具有一个或多个 *_url 链接到其他资源的属性。这些旨在提供显式 URL，以便适当的 API 客户端不需要自己构造 URL。强烈建议 API 客户端使用这些。这样做将使开发人员将来更容易升级 API。预期所有 URL 都是正确的 RFC 6570 URI 模板。

分页

默认情况下，返回多个项目的请求将被分页为 30 个项目。可以使用 ?page 参数指定其他页面。对于某些资源，还可以使用 ?per_page 参数设置最大 100 的自定义页面大小。

curl'https://api.blog.com/user/lzz/blogs?page=2&per_page=100'

请注意，页码是基于 1 的，省略该 ?page 参数将返回第一页。

链接标题

该链接头包括分页信息：

Link: <https://api.blog.com/user/lzz/blogs?page=3&per_page=100>; rel="next",
  <https://api.blog.com/user/lzz/blogs?page=50&per_page=100>; rel="last"

该示例包括换行符，以提高可读性。

此 Link 响应标头包含一个或多个超媒体链接关系，其中一些可能需要扩展为 URI 模板。

可能的 rel 值为：

名称	描述
next	结果的下一页的链接关系。
last	最后一页结果的链接关系。
first	结果首页的链接关系。
prev	前一页结果的链接关系。

限速

对于使用基本身份验证的 API 请求，每小时最多可以进行 5000 个请求。经过身份验证的请求都与经过身份验证的用户相关联 。

对于未经身份验证的请求，速率限制允许每小时最多 60 个请求。未经身份验证的请求与原始 IP 地址相关联，而不与发出请求的用户相关联。

任何 API 请求返回的 HTTP 标头都会显示当前的速率限制状态：

curl -i https://api.blog.com/users/lzz
HTTP/1.1 200 OK
Date: Wed, 20 Nov 2019 23:33:14 GMT
Status: 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 56
X-RateLimit-Reset: 1372700873

标头名称	描述
X-RateLimit-Limit	每小时允许发出的最大请求数。
X-RateLimit-Remaining	当前速率限制窗口中剩余的请求数。
X-RateLimit-Reset	当前速率限制窗口重置的时间，以UTC纪元秒为单位。

如果超出速率限制，则会返回错误响应：

HTTP/1.1 403 Forbidden
Date: Wed, 20 Nov 2019 23:33:14 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.blog.com/v3/#rate-limiting"
}