通过模式发现API设计面临的挑战并采取相应的解决措施
合理规划API端点和操作
设计请求消息和响应消息及其表示形式
优化消息设计以提高质量
规划API的演进
编写API契约并向相关方传达这些契约
搭配使用各种模式以解决实际问题,并做出正确的权衡
第Ⅰ部分 基础知识概述
第1章 API基础知识 3
1.1 从本地接口到远程API 3
1.1.1 分布式系统和远程API概述 4
1.1.2 远程API：通过集成协议访问服务 5
1.1.3 API的重要性 6
1.2 API设计中的决策驱动因素 11
1.2.1 API的成功要素 11
1.2.2 API设计有何不同 12
1.2.3 API设计难在哪里 12
1.2.4 架构方面的重要需求 14
1.2.5 开发者体验 15
1.3 远程API的领域模型 16
1.3.1 通信参与者 16
1.3.2 API端点提供描述操作的API契约 17
1.3.3 消息是对话的组成部分 17
1.3.4 消息结构和表示 18
1.3.5 API契约 19
1.3.6 全书使用的领域模型 20
1.4 本章小结 20
第2章 Lakeside Mutual案例研究 23
2.1 业务背景和要求 23
2.1.1 用户故事和期望的系统质量 23
2.1.2 分析级别的领域模型 24
2.2 架构概述 26
2.2.1 系统上下文 26
2.2.2 应用程序架构 27
2.3 API设计活动 29
2.4 目标API规范 29
2.5 本章小结 30
第3章 API决策叙述 33
3.1 前奏：模式作为决策选项，设计驱动力作为决策标准 33
3.2 API的基础性决策和模式 35
3.2.1 API可见性 36
3.2.2 API集成类型 39
3.2.3 API文档 41
3.3 API角色和职责的相关决策 43
3.3.1 端点的架构角色 44
3.3.2 剖析各类信息持有者角色 46
3.3.3 定义操作职责 50
3.4 选择消息表示模式 52
3.4.1 表示元素的扁平结构与嵌套结构 54
3.4.2 元素构造型 58
3.5 插叙：Lakeside Mutual案例中的职责和结构模式 61
3.6 API质量治理的相关决策 62
3.6.1 API客户端的识别和身份验证 63
3.6.2 对API的使用情况进行计量和计费 65
3.6.3 防止API客户端过度使用API 67
3.6.4 明确规定质量目标和处罚机制 69
3.6.5 报告和处理错误 70
3.6.6 显式上下文表示 71
3.7 API质量改进的相关决策 73
3.7.1 分页 73
3.7.2 避免非必要数据传输的其他手段 76
3.7.3 处理消息中的引用数据 79
3.8 API演进的相关决策 81
3.8.1 版本控制和兼容性管理 83
3.8.2 版本发布和停用的相关策略 85
3.9 插叙：Lakeside Mutual案例中的质量和演进模式 88
3.10 本章小结 90
第Ⅱ部分 模式
第4章 模式语言简介 95
4.1 定位和范围 95
4.2 使用模式的原因和方法 97
4.3 模式一览 98
4.3.1 结构组织：按范围查找模式 98
4.3.2 主题分类：查找模式 99
4.3.3 时间维度：遵循设计完善阶段 100
4.3.4 浏览方式：从Map到MAP 101
4.4 基础模式：API可见性和集成类型 102
4.4.1 Frontend Integration模式 103
4.4.2 Backend Integration模式 104
4.4.3 Public API模式 105
4.4.4 Community API模式 106
4.4.5 Solution-Internal API模式 108
4.4.6 基础模式小结 109
4.5 基本结构模式 109
4.5.1 Atomic Parameter模式 110
4.5.2 Atomic Parameter List模式 112
4.5.3 Parameter Tree模式 114
4.5.4 Parameter Forest模式 116
4.5.5 基本结构模式小结 118
4.6 本章小结 119
第5章 定义端点类型和操作 121
5.1 API角色和职责简介 121
5.1.1 设计挑战和期望质量 122
5.1.2 本章讨论的模式 123
5.2 端点角色(服务粒度) 125
5.2.1 Processing Resource模式 125
5.2.2 Information Holder Resource模式 132
5.2.3 Operational Data Holder模式 138
5.2.4 Master Data Holder模式 142
5.2.5 Reference Data Holder模式 146
5.2.6 Link Lookup Resource模式 149
5.2.7 Data Transfer Resource模式 154
5.3 操作职责 161
5.3.1 State Creation Operation模式 162
5.3.2 Retrieval Operation模式 167
5.3.3 State Transition Operation模式 171
5.3.4 Computation Function模式 180
5.4 本章小结 186
第6章 设计请求消息和响应消息表示 189
6.1 消息表示设计简介 189
6.1.1 消息表示设计面临的挑战 190
6.1.2 本章讨论的模式 190
6.2 元素构造型 191
6.2.1 Data Element模式 192
6.2.2 Metadata Element模式 196
6.2.3 Id Element模式 203
6.2.4 Link Element模式 207
6.3 特殊用途的表示元素 212
6.3.1 API Key模式 213
6.3.2 Error Report模式 217
6.3.3 Context Representation模式 221
6.4 本章小结 231
第7章 优化消息设计以改善质量 233
7.1 API质量简介 233
7.1.1 改善API质量面临的挑战 234
7.1.2 本章讨论的模式 234
7.2 消息粒度 236
7.2.1 Embedded Entity模式 237
7.2.2 Linked Information Holder模式 241
7.3 由客户端决定获取哪些消息内容(响应塑造) 245
7.3.1 Pagination模式 246
7.3.2 Wish List模式 253
7.3.3 Wish Template模式 256
7.4 消息交换优化(对话效率) 260
7.4.1 Conditional Request模式 261
7.4.2 Request Bundle模式 265
7.5 本章小结 269
第8章 API演进 271
8.1 API演进简介 271
8.1.1 API演进面临的挑战 271
8.1.2 本章讨论的模式 274
8.2 版本控制和兼容性管理 274
8.2.1 Version IDentifier模式 275
8.2.2 Semantic Versioning模式 280
8.3 生命周期管理保证 284
8.3.1 Experimental Preview模式 284
8.3.2 Aggressive Obsolescence模式 287
8.3.3 Limited Lifetime Guarantee模式 291
8.3.4 Two in Production模式 294
8.4 本章小结 298
第9章 编写和传达API契约 301
9.1 API文档简介 301
9.1.1 编写API文档时面临的挑战 301
9.1.2 本章讨论的模式 303
9.2 文档模式 303
9.2.1 API Description模式 304
9.2.2 Pricing Plan模式 309
9.2.3 Rate Limit模式 313
9.2.4 Service Level Agreement模式 316
9.3 本章小结 320
第Ⅲ部分 实践应用
第10章 实际的模式案例 325
10.1 瑞士抵押贷款业务的大规模流程集成 325
10.1.1 业务背景和领域 325
10.1.2 技术方面的挑战 326
10.1.3 API的角色和状态 327
10.1.4 模式使用和实现 328
10.1.5 回顾与展望 333
10.2 建筑施工领域的报价和订购流程 335
10.2.1 业务背景和领域 335
10.2.2 技术方面的挑战 336
10.2.3 API的角色和状态 336
10.2.4 模式使用和实现 338
10.2.5 回顾与展望 339
10.3 本章小结 340
第11章 结语 341
11.1 简要回顾 341
11.2 API研究：模式重构、微服务领域特定语言及其他 342
11.3 未来展望 343
11.4 其他资源 344
11.5 写在最后 344
附录A 端点识别和模式选择指南 345
附录B Lakeside Mutual案例的实现 353
附录C 微服务领域特定语言 361
