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

本书从“由外而内”的角度引入 API 设计，重视反映客户和产品团队的声音，将需求映射到特定的、组织良好的 API，为编写这些 API 选择正确的风格，并从零开始实现了一个真实的例子，旨在为设计新 API 或扩展现有 API 的人提供指导，帮助他们了解如何通过正确的设计过程来交付优秀的 API，如何与设计团队、客户和其他涉众就具体的成果达成一致，如何确定正确的 API 并将操作整合成统一的 API 配置文件，以及如何使 API 程序实现可伸缩的设计和管理过程。本书适合所有参与规划或构建 API 的读者阅读，包括架构师、开发人员、团队领导者、单团队和多团队环境中的项目管理人员，以及相关技术人员或业务专业人员。

[美]詹姆斯·希金博特姆（James Higginbotham）是一名软件开发人员和架构师，在开发、部署应用程序和 API 设计方面拥有超过 25 年的经验。他擅长与银行、商业保险、酒店、旅游、航空等行业的团队和企业合作，能帮助团队将业务、产品和技术策略统一到更易组合和模块化的企业平台，指导企业完成数字化转型之旅。 詹姆斯曾多次举办研讨会，热衷向跨职能团队推荐他提出的 ADDR 流程——通过基于产品的思维来确保业务和技术之间的一致性，以提供出色的客户体验。

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