HTTP API 设计指南（响应部分）

痛定思痛。 2023-08-17 15:32 110阅读 0赞

## 前言 ##

这篇指南介绍描述了 HTTP+JSON API 的一种设计模式，最初摘录整理自 Heroku 平台的 API 设计指引 [Heroku 平台 API 指引][Heroku _ API]。

这篇指南除了详细介绍现有的 API 外，Heroku 将来新加入的内部 API 也会符合这种设计模式，我们希望非 Heroku 员工的API设计者也能感兴趣。

我们的目标是保持一致性，专注业务逻辑同时避免过度设计。我们一直试图找出一种良好的、一致的、显而易见的 API 设计方法，而并不是所谓的"最终/理想模式"。

我们假设你熟悉基本的 HTTP+JSON API 设计方法，所以本篇指南并不包含所有的 API 设计基础。

我们欢迎你为这篇指南做[贡献][Link 1]。

--------------------

## 提供资源的(UU)ID ##

在默认情况给每一个资源一个`id`属性。除非有更好的理由，否则请使用UUID。不要使用那种在服务器上或是资源中不是全局唯一的标识，尤其是自动增长的id。

生成小写的UUID格式 `8-4-4-4-12`，例如：

"id": "01234567-89ab-cdef-0123-456789abcdef"

## 提供标准的时间戳 ##

为资源提供默认的创建时间 `created_at` 和更新时间 `updated_at`，例如:

{
      ...
      "created_at": "2012-01-01T12:00:00Z",
      "updated_at": "2012-01-01T13:00:00Z",
      ...
    }

有些资源不需要使用时间戳那么就忽略这两个字段。

## 使用UTC（世界标准时间）时间，用ISO8601进行格式化 ##

在接收和返回时都只使用UTC格式。ISO8601格式的数据，例如:

"finished_at": "2012-01-01T12:00:00Z"

## 嵌套外键关系 ##

使用嵌套对象序列化外键关联，例如:

{
      "name": "service-production",
      "owner": {
        "id": "5d8201b0..."
      },
      // ...
    }

而不是像这样:

{
      "name": "service-production",
      "owner_id": "5d8201b0...",
      ...
    }

这种方式尽可能的把相关联的资源信息内联在一起，而不用改变资源的结构，或者引入更多的字段，例如:

{
      "name": "service-production",
      "owner": {
        "id": "5d8201b0...",
        "name": "Alice",
        "email": "alice@heroku.com"
      },
      ...
    }

## 生成结构化的错误 ##

响应错误的时，生成统一的、结构化的错误信息。包含一个机器可读的错误 `id`，一个人类能识别的错误信息（`message`），根据情况可以添加一个`url`来告诉客户端关于这个错误的更多信息以及如何去解决它，例如:

HTTP/1.1 429 Too Many Requests

{
      "id":      "rate_limit",
      "message": "Account reached its API rate limit.",
      "url":     "https://docs.service.com/rate-limits"
    }

文档化客户端可能遇到的错误信息格式，以及这些可能的错误信息`id`。

## 显示频率限制状态 ##

客户端的访问速度限制可以维护服务器的良好状态，保证为其他客户端请求提供高性的服务。你可以使用[token bucket algorithm][]技术量化请求限制。

为每一个带有`RateLimit-Remaining`响应头的请求，返回预留的请求tokens。

## 保证响应JSON最小化 ##

请求中多余的空格会增加响应大小，而且现在很多的HTTP客户端都会自己输出可读格式（"prettify"）的JSON。所以最好保证响应JSON最小化，例如：

{"beta":false,"email":"alice@heroku.com","id":"01234567-89ab-cdef-0123-456789abcdef","last_login":"2012-01-01T12:00:00Z","created_at":"2012-01-01T12:00:00Z","updated_at":"2012-01-01T12:00:00Z"}

而不是这样：

{
      "beta": false,
      "email": "alice@heroku.com",
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "last_login": "2012-01-01T12:00:00Z",
      "created_at": "2012-01-01T12:00:00Z",
      "updated_at": "2012-01-01T12:00:00Z"
    }

你可以提供可选的方式为客户端提供更详细可读的响应，使用查询参数（例如：`?pretty=true`）或者通过`Accept`头信息参数（例如：`Accept: application/vnd.heroku+json; version=3; indent=4;`）

[Heroku _ API]: https://devcenter.heroku.com/articles/platform-api-reference
[Link 1]: https://github.com/interagent/http-api-design/blob/master/CONTRIBUTING.md
[token bucket algorithm]: http://en.wikipedia.org/wiki/Token_bucket