WEB API设计原则通过API和微服务实现价值交付

第 一部分 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