实用 Web API 规范

为什么我们需要 API 统一规范

• 容易理解，提高效率：服务提供方和消费方使用统一形式、结构和使用方式，以及统一的生产消费协议，从而减少沟通成本。

• 专家经验：它包含最佳的工程实践，常见场景都有对应的解决方案，避免了每个人都要重新思考整个 API 系统。 例如，如何处理 API 缓存？如何进行鉴权？如何进行数据格式处理？

• 面向未来的扩展，需要稳定的协议：协议是抽象的、独立于实现的，不是每个人都具备 设计面向不确定系统的能力，一些广泛使用的技术则为更广泛的场景做了规划。

规范的原则

• 简洁：简洁是抵抗复杂性的最直接和最有效的策略，利用简洁原则降低复杂度，避免复杂性的滋生和扩散；

• 一致性：统一的设计模式和延续的设计风格有助于降低工程成本和工程师的心理负担；

• 遵循现实：遵循现有工程领域的抽象和分层（例如 HTTP，REST，RBAC，OIDC 等），不要自己发明新的概念， 要始终思考这个问题是否只有自己遇到了（答案肯定是否定的）。

REST 到底行不行？

1. The Swamp of POX，使用 HTTP 承载 Legacy 协议（XML）

2. Resources：使用资源抽象

3. HTTP Verbs：使用丰富的 HTTP Verbs

4. Hypermedia Controls：使用 rel 链接进行 API 资源整合，JSON:API 是登峰造极的表现

• 它充分利用了 HTTP 协议的设计（HTTP Protocol）

• 它具有出色的资源定位能力（Identification of resources）

• 它设计了完备的资源操作方式（Manipulation of resources）

• 它具备自解释性（Self-descriptive messages）

• 它支持多种形态的呈现方式（hypermedia as the engine of application state）

• 并非所有请求都可以用资源描述，比如登录（/login）操作，转换成 session 就非常绕口； 同样的问题在转账这种业务也会出现。HTTP 有限的动词无法支撑所有业务场景。

• REST 并未提供针对必然面临的问题，如分页、返回体具体结构、错误处理和鉴权等，明确的解决方案。

• 对于复杂的查询（如搜索 Search），RESTful API 的查询参数可能会变得非常复杂，难以维护。

Web API 规范的选择题

URL 最佳实践

• 定位资源（这就回答分页是否应该在 Header）

• 自解释（可读性强，URL 自身即包含核心信息）

• 安全（不能包含用户认证信息，OAuth 为了解这个花了很多精力，防伪造）

1. 使用 POST 方法与自定义动词，例如 POST /apis/books/borrow，表示借书这一动作；

2. 创建一个借书记录，使用资源新增方式来结构不存在的动作，例如 POST /apis/books/borrow-log/；

• 使用 ID：ID 通常与数据库自增 ID 绑定。

• 使用 GUID：例如 UUID，尽管不那么精确。

• 使用可读性和稳定性标识符（Readable Stable Identity）：通常使用名称、UID 或特定 ID（如主机名、IP 地址或序列号）来标识， 要求该标识符具有稳定性且全局唯一，在内部系统中非常有用。

# 原始 URL
https://test.com/apis/v3/books?sort=hot&limit=10

# Alias URL
https://test.com/apis/v3/books/hot

Header 最佳实践

• 200 OK：请求已成功处理，服务器返回了响应。

• 201 Created：请求已经被成功处理，并且在服务器上创建了一个新的资源。

• 202 Accepted：请求已被服务器接受，但尚未执行。该状态码通常用于异步处理。

• 204 No Content：请求已成功处理，但是服务器没有返回任何响应体内容。

Request 最佳实践

Response 最佳实践

• Business Object（BO）：原始的业务模型

• Data Object（DO）：存储到 RDBMS 的模型，所以必须是打平的字段结构，有时候一个 BO 会对应到多个 DO

• View Object（VO）：呈现到表现层的模型，只保留用户需要看到信息，比如会去掉敏感信息

• Data Transfer Object（DTO）：用来在 RPC 系统进行传输的模型，一般和 原始的 Model 差异不大，根据不同序列化系统会有差异 （比如枚举的处理）

• Rich Model：用来描述一个丰富模型，这个模型包含了几乎所有需要用的的数据，也允许子资源进行嵌套

• Tiny Model：是一个精简模型，往往用来在列表 API 里面被使用

{
  "data": {
    "id": 42,
    "name": "朝花夕拾",
    "relationships": {
      "comments": "http://www.domain.com/book/42/comments",
      "author": [
        "http://www.domain.com/author/鲁迅"
      ]
    }
  }
}

{
  "data": {
    "id": 42,
    "name": "朝花夕拾",
    "relationships": {
      "comments": "http://www.domain.com/book/42/comments",
      "authors": [
        "http://www.domain.com/author/鲁迅"
      ]
    }
  },
  "includes": {
    "comments": [
      {
        "id": 91,
        "author": "匿名",
        "content": "非常棒"
      }
    ],
    "authors": [
      {
        "name": "鲁迅",
        "description": "鲁迅原名周树人"
      }
    ]
  }
}

{
  "data": {
    "id": 42,
    "name": "朝花夕拾",
    "comments": [
      {
        "id": 91,
        "author": "匿名",
        "content": "非常棒"
      }
    ],
    "authors": [
      {
        "name": "鲁迅",
        "description": "鲁迅原名周树人"
      }
    ]
  }
}

其他

• Azure SDK 设计规范 General Guidelines: API Design | Azure SDKs

• Posix API 范例（比如 File Low-Level I/O (The GNU C Library))

一张风格 Checklist

Github 风格

Azure 风格

我个人风格

题外话 - Apple Music 的一个有趣设计

题外话 - 为什么 GraphQL 不行

最后

• api-guidelines/Guidelines.md at master · microsoft/api-guidelines

• GitHub’s APIs

• Web API design best practices - Azure Architecture Center | Microsoft Learn

• API 设计最佳实践的思考 - 谷朴