第 一部分 Web API设计简介
第 1章 API设计原则 3
1.1 Web API设计要素 4
1.1.1 业务功能 4
1.1.2 产品思维 4
1.1.3 开发者体验 5
1.2 API设计即沟通 6
1.3 审查软件设计的原则 7
1.3.1 模块化 7
1.3.2 封装 8
1.3.3 高内聚和松耦合 8
1.4 基于资源的API设计 9
1.5 资源不是对象或领域模型 11
1.6 基于资源的API交换消息 11
1.7 Web API设计原则 13
1.8 小结 13
第 2章 协作式API设计 15
2.1 为什么需要API设计流程？ 15
2.2 API设计流程反模式 17
2.2.1 泄露抽象反模式 17
2.2.2 下一个版本设计修复反模式 18
2.2.3 英雄设计工作反模式 18
2.2.4 未使用的API反模式 19
2.3 API设计优先的方法 19
2.4 API设计优先并保持敏捷 20
2.4.1 重新审视敏捷宣言 21
2.4.2 API设计优先的敏捷性 21
2.5 对齐-定义-设计-优化流程 22
2.6 DDD在API设计中的作用 24
2.7 API设计涉及每一个人 25
2.8 有效应用ADDR流程 26
2.9 小结 26
第二部分 对齐API的结果
第3章 明确数字功能 29
3.1 确保利益相关者思路对齐 30
3.2 什么是数字功能？ 31
3.3 专注于要完成的工作 32
3.4 什么是任务用例？ 33
3.5 任务用例的组成部分 33
3.6 为API编写任务用例 34
3.6.1 方法1：当问题已知时 35
3.6.2 方法2：当期望的结果已知时 35
3.6.3 方法3：当数字功能已确定时 35
3.7 克服任务用例的挑战 36
3.7.1 挑战1：任务用例过于详细 36
3.7.2 挑战2：任务用例以功能为中心 36
3.7.3 挑战3：任务用例需要额外的用户上下文 37
3.8 收集任务用例的技巧 37
3.9 现实世界中的API设计项目 38
3.10 任务用例示例 39
3.11 小结 39
第4章 收集操作和步骤 41
4.1 将任务用例扩展为操作及其对应的步骤 42
4.1.1 确定每个任务用例的操作 43
4.1.2 将每个操作分解为若干步骤 43
4.1.3 如果需求不明确，怎么办？ 44
4.2 通过事件风暴实现协作式 理解 44
4.3 事件风暴的工作方式 46
4.3.1 步骤1：明确领域事件 46
4.3.2 步骤2：创建事件描述 47
4.3.3 步骤3：查看描述并确定差距 48
4.3.4 步骤4：扩展领域理解力 49
4.3.5 步骤5：查看最终描述 50
4.4 事件风暴的好处 52
4.5 主持事件风暴会议 53
4.5.1 准备：收集必要的材料 用品 54
4.5.2 分享：沟通事件风暴会议 55
4.5.3 主持：进行事件风暴会议 56
4.5.4 总结：收集操作和步骤 56
4.5.5 跟进：会后建议 57
4.5.6 定制流程 57
4.6 小结 58
第三部分 定义候选API
第5章 明确API边界 61
5.1 避免API边界反模式 62
5.1.1 大型一体化API反模式 62
5.1.2 过载API反模式 62
5.1.3 辅助API反模式 63
5.2 有界上下文、子域和API 63
5.3 使用事件风暴探索API边界 64
5.4 通过操作找到API边界 67
5.5 为API命名并确定其范围 68
5.6 小结 69
第6章 API建模 71
6.1 什么是API建模？ 72
6.2 API建模流程 74
6.2.1 步骤1：收集API配置文件摘要 74
6.2.2 步骤2：确定资源 75
6.2.3 步骤3：定义API分类法 77
6.2.4 步骤4：添加操作事件 79
6.2.5 步骤5：扩展操作的详细信息 80
6.3 用序列图验证API模型 81
6.4 评估API的优先级和重用性 83
6.5 小结 84
第四部分 设计API
第7章 基于REST的API设计 87
7.1 什么是基于REST的API？ 88
7.1.1 REST是客户-服务器体系结构 90
7.1.2 REST是以资源为中心的 90
7.1.3 REST是基于消息的 91
7.1.4 REST支持分层架构 91
7.1.5 REST支持按需编码 93
7.1.6 超媒体控制 93
7.1.7 什么时候选择REST 96
7.2 REST API设计流程 97
7.2.1 步骤1：设计资源URL路径 97
7.2.2 步骤2：将API操作映射到HTTP方法上 99
7.2.3 步骤3：分配响应代码 100
7.2.4 步骤4：记录REST API设计 102
7.2.5 步骤5：分享并收集反馈 106
7.3 选择一种表征格式 106
7.3.1 资源序列化 107
7.3.2 超媒体序列化 108
7.3.3 超媒体消息传递 109
7.3.4 语义超媒体消息传递 110
7.4 常见的REST设计模式 113
7.4.1 创建-读取-更新-删除 113
7.4.2 扩展资源生命周期支持 113
7.4.3 单例资源 114
7.4.4 后台（队列）作业 115
7.4.5 REST中的长期运行事务支持 116
7.5 小结 117
第8章 RPC和基于查询的API设计 119
8.1 什么是基于RPC的API？ 120
8.1.1 gRPC 121
8.1.2 使用RPC时应该考虑的因素 122
8.2 RPC API设计流程 123
8.2.1 步骤1：确定RPC操作 123
8.2.2 步骤2：细化RPC操作 124
8.2.3 步骤3：记录API设计 125
8.3 什么是基于查询的API？ 126
8.3.1 了解OData 127
8.3.2 探索GraphQL 128
8.4 基于查询的API设计流程 130
8.4.1 步骤1：设计资源和图结构 130
8.4.2 步骤2：设计查询和突变操作 131
8.4.3 步骤3：记录API设计 132
8.5 小结 134
第9章 用于事件和流的异步API 135
9.1 API轮询的问题 136
9.2 异步API创造新的可能性 137
9.3 回顾消息传递的基础知识 138
9.3.1 消息传递的样式和位置 139
9.3.2 消息的要素 140
9.3.3 了解消息代理 141
9.3.4 点对点消息分发（队列） 142
9.3.5 扇出消息分发（主题） 143
9.3.6 消息流基础知识 144
9.4 异步API样式 145
9.4.1 使用Webhooks的服务器通知 146
9.4.2 使用服务器发送事件的服务器推送 147
9.4.3 通过WebSocket的双向通知 148
9.4.4 gRPC流 149
9.4.5 选择异步API样式 151
9.5 设计异步API 151
9.5.1 命令消息 152
9.5.2 事件通知 152
9.5.3 事件承载的状态转移事件 153
9.5.4 事件批处理 155
9.5.5 事件排序 156
9.6 记录异步API 156
9.7 小结 158
第五部分 优化API设计
第 10章 从API到微服务 161
10.1 什么是微服务？ 162
10.2 微服务降低协调成本 164
10.3 API产品和微服务之间的区别 165
10.4 权衡微服务的复杂性 165
10.4.1 自助服务基础设施 166
10.4.2 独立的发布周期 166
10.4.3 转向单一团队的所有权 166
10.4.4 组织结构和文化影响 166
10.4.5 数据所有权的转移 167
10.4.6 分布式数据管理和治理 167
10.4.7 分布式系统的挑战 168
10.4.8 弹性、故障转移和分布式事务 168
10.4.9 重构和共享代码带来的挑战 169
10.5 同步和异步的微服务 169
10.6 微服务架构的样式 171
10.6.1 直接服务通信 171
10.6.2 基于API的编排 172
10.6.3 基于单元的架构 172
10.7 合理调整微服务的规模 173
10.8 API分解为微服务 174
10.8.1 步骤1：明确候选微服务 174
10.8.2 步骤2：将微服务添加到API序列图中 176
10.8.3 步骤3：使用微服务设计画布，以收集设计细节 177
10.8.4 其他微服务设计注意事项 178
10.9 过渡到微服务时的注意事项 179
10.10 小结 180
第 11章 改善开发者体验 181
11.1 创建一个API模拟实现 182
11.1.1 API静态模拟 183
11.1.2 API原型模拟 184
11.1.3 基于README的模拟 185
11.2 提供辅助库和SDK 187
11.2.1 提供辅助库的选项 187
11.2.2 对辅助库版本化 188
11.2.3 辅助库文档和测试 188
11.3 为API提供CLI 189
11.4 小结 191
第 12章 API测试策略 193
12.1 验收测试 194
12.2 自动化安全测试 194
12.3 运维监控 195
12.4 API契约测试 195
12.5 选择工具，以加快测试速度 197
12.6 API测试的挑战 197
12.7 让API测试不可或缺 198
12.8 小结 199
第 13章 为API设计制作文档 201
13.1 API文档的重要性 202
13.2 API描述格式 202
13.2.1 OpenAPI规范 203
13.2.2 API Blueprint 205
13.2.3 RAML 207
13.2.4 JSON Schema 211
13.2.5 使用ALPS的API配置文件 212
13.2.6 使用APIs.json改进API发现功能 213
13.3 使用代码示例扩展文档 215
13.3.1 先写好入门代码示例 215
13.3.2 使用工作流示例扩展文档 216
13.3.3 错误案例和生产就绪的示例 217
13.4 从参考文档到开发者门户网站 217
13.4.1 通过开发者门户网站提高API采用率 218
13.4.2 优秀的开发者门户网站的要素 218
13.5 有效的API文档 219
13.5.1 问题1：你的API如何解决我的问题？ 220
13.5.2 问题2：每个API操作都支持什么功能？ 220
13.5.3 问题3：我如何开始使用API？ 220
13.5.4 技术文档撰写人在API文档中的角色 221
13.6 最小可行的门户 222
13.6.1 第 1个阶段：最小可行的门户 222
13.6.2 第 2个阶段：改进 223
13.6.3 第3个阶段：专注于增长 224
13.7 用来制作开发者门户网站的工具和框架 224
13.8 小结 225
第 14章 为变更而设计 227
14.1 变更对现有API的影响 227
14.1.1 进行API设计差距分析 228
14.1.2 确定什么最适合API消费者 228
14.1.3 变更策略 229
14.1.4 变更管理是建立在信任之上的 230
14.2 API版本控制策略 230
14.2.1 常见的非破坏性变更 231
14.2.2 不兼容的变更 231
14.2.3 API版本和修订版本 232
14.2.4 API版本控制方法 233
14.2.5 API版本的商业考虑因素 234
14.3 弃用API 234
14.3.1 制订弃用策略 235
14.3.2 宣布弃用 235
14.4 创建一个API稳定性契约 236
14.5 小结 237
第 15章 保护API 239
15.1 危害API的潜在因素 239
15.2 基本的API保护实践 240
15.3 API保护的组件 242
15.3.1 API网关 242
15.3.2 APIM层 242
15.3.3 服务网格 243
15.3.4 WAF 244
15.3.5 内容分发网络 244
15.3.6 智能API保护 244
15.4 API网关拓扑结构 245
15.4.1 APIM托管选项 245
15.4.2 API网络流量注意事项 248
15.4.3 拓扑结构1：API网关直连到API服务器 248
15.4.4 拓扑结构2：API网关路由到服务 249
15.4.5 拓扑结构3：多个API网关实例 250
15.5 身份和访问管理 251
15.5.1 密码和API密钥 251
15.5.2 API令牌 251
15.5.3 引用传递与值传递的API令牌 253
15.5.4 OAuth 2.0和OpenID Connect 253
15.6 构建内部API网关之前的注意事项 255
15.6.1 原因1：API安全性是一个不断变化的目标 255
15.6.2 原因2：需要的时间比预期的更长 255
15.6.3 原因3：预期的表现需要时间 256
15.6.4 辅助库怎么样？ 256
15.7 小结 257
第 16章 继续API设计旅程 259
16.1 建立API样式指南 259
16.1.1 鼓励遵守样式指南的方法 260
16.1.2 选择样式指南的“基调” 261
16.1.3 启动API样式指南的入门技巧 261
16.1.4 支持多种API样式 262
16.2 进行API设计审查 262
16.2.1 从文档审查开始 263
16.2.2 检查标准和设计是否对齐 264
16.2.3 审查测试覆盖率 264
16.2.4 添加试用支持 265
16.3 鼓励重用文化 265
16.4 旅程才刚刚开始 266
附录A HTTP入门知识 267
A.1 HTTP概述 267
A.2 统一资源定位符 268
A.3 HTTP请求 269
A.4 HTTP响应 270
A.5 常见HTTP方法 271
A.6 HTTP响应代码 272
A.7 内容协商 273
A.8 缓存控制 275
A.9 条件性请求 276
A.10 HTTP中的并发控制 278
A.11 小结 280
