Principles of Web API Design: Delivering Value with APIs and Microservices

书籍定位

《Principles of Web API Design》是Addison Wesley出版社于2022年出版的Web API设计权威指南，作者James Higginbotham基于25年软件开发和架构经验，为读者提供了一套完整的API设计原则和过程。本书强调API设计不仅仅是技术实现，更是业务能力、产品思维和开发者体验的有机结合，旨在帮助团队设计出能够真正交付价值的API。

核心内容

本书的核心是ADDR（Align-Define-Design-Refine）设计过程，分为五个部分：

第一部分：Web API设计导论（第1-2章） 介绍API设计的重要性，强调API是永久的——一旦投入生产就难以进行重大变更。作者提出API设计的三个关键要素：业务能力、产品思维和开发者体验。第1章深入探讨软件设计原则（模块化、封装、高内聚低耦合）如何应用于API设计，并区分资源与数据模型。第2章介绍协作式API设计方法，避免常见反模式（如泄漏抽象、英雄式设计努力等）。

第二部分：对齐API成果（第3-4章） 专注于确保API设计团队与所有客户和利益相关者保持一致。第3章介绍数字能力的概念，使用"待完成工作"框架和任务故事来捕获API需求。第4章详细说明如何将任务故事扩展为活动和步骤，使用EventStorming技术进行协作理解，帮助团队共同构建业务流程的认知模型。

第三部分：定义候选API（第5-6章） 识别交付期望成果所需的API和API操作。第5章探讨如何识别API边界，避免常见边界反模式（如巨型一体化API、过载API等）。第6章详细介绍API建模过程，包括捕获API配置文件摘要、识别资源、定义资源分类、添加操作事件等步骤，并使用序列图验证API模型。

第四部分：设计API（第7-9章） 将API配置文件转换为适合目标开发者的API风格。第7章全面介绍RESTful API设计过程，包括设计资源URL路径、映射API操作到HTTP方法、分配响应代码等。第8章涵盖RPC和基于查询的API设计，包括gRPC协议和GraphQL。第9章专注于异步API设计，用于事件和流处理，涵盖Webhooks、Server-Sent Events、WebSocket等模式。

第五部分：精炼API设计（第10-15章） 基于文档、测试和反馈改进API设计。第10章探讨从API到微服务的过渡，包括微服务架构风格、服务大小确定和分解策略。第11章专注于改善开发者体验，包括创建模拟API实现、提供辅助库和CLI工具。第12章介绍API测试策略，包括验收测试、安全测试和合同测试。第13章详细说明API文档化，涵盖OpenAPI、API Blueprint等描述格式。第14章讨论为变更而设计，包括API版本策略和弃用管理。第15章关注API保护，涵盖API网关、身份管理和安全实践。

适用读者

• 产品负责人和产品经理：深入了解团队设计API所需的元素
• 软件架构师和开发者：学习如何通过应用软件架构原则来设计API
• 技术文档编写者：识别如何在API设计过程中贡献价值
• 任何参与API设计的人员：无论是开发角色还是非开发角色

阅读建议

本书采用从外到内的视角，强调API设计是一个沟通过程，涉及跨网络边界、与消费开发者以及与市场的沟通。建议读者按顺序阅读，特别是关注ADDR过程的应用。书中包含大量实际案例，如Capital One的API转型案例，展示了如何将API思维应用于银行业。对于需要HTTP基础知识的读者，附录提供了入门指南。本书不包含具体代码清单，专注于设计原则和过程，适合所有技术背景的读者。