做集成的工程师，最该读这本 API 设计书

Designing Web APIs 的目录共 11 章：从“What’s an API?”开始，经过安全和设计最佳实践，第 6 章转向 Scaling APIs（API 扩展），随后讲变更管理和开发者计划。换句话说，这本书很大一部分讲的是 API 有了真实用户之后的事。

对前线部署工程师（FDE）来说，这部分最值得花钱。你很少需要从零设计 API。更常见的情况是：面前摆着一个经过三代团队之手的客户 API，你得在演示截止日期前把自己的系统接上去。

这本书是写给另一方的，也就是构建和运营 API 的人。但站在集成方的角度读，它能帮你理解客户的 API 为什么长成这样，并预判它会在哪里出问题。

这是一本什么书？

全名是 Designing Web APIs: Building APIs That Developers Love，作者 Brenda Jin、Saurabh Sahni 和 Amir Shevat，O’Reilly Media 于 2018 年出版。平装本（ISBN 9781492026921）共 232 页；部分图书馆记录因版本不同，页数有出入。目标读者是开发者、架构师和技术负责人。

书的简介坦言，打造一个被广泛使用的 API 并培育繁荣的开发者生态非常困难。书中有构建 API 并在生产环境中运行的动手练习，还有工作表、检查清单，以及来自 Slack、Stripe、Facebook、Microsoft、Cloudinary、Oracle 和 GitHub 的案例。附录 A 的标题是 API Design Worksheets（API 设计工作表）。

由于出版于 2018 年，应把它当作一本讲思路的书，而不是工具参考手册。设计 API 时提问的方式，变化远比工具慢。

做集成的人，为什么要读写给设计者的书？

你在客户现场遇到的每个 API，都是一连串决策留下的痕迹。曾经有人选定了范式，选择了安全模型，设定了负载限制，之后还得在不影响现有客户端的前提下修改 API。这本书的目录正好依次覆盖这几个阶段：范式、安全、扩展、变更管理。

一旦知道设计者在每个阶段要权衡什么，你读客户 API 文档的方式就会不同。你不再只问哪个端点返回哪些数据，而会开始问：他们做了哪些取舍，这些取舍的代价会落在你集成的哪个环节。

带到客户现场的三个思路

第一，范式决定了 API 的形态。书中把 API Paradigms（API 范式）一章紧接在定义 API 的章节之后，其中一个目标就是区分请求-响应式 API 和事件驱动式 API，包括 WebHooks 和 WebSockets。

在客户现场，一开始就判断准 API 风格，能避免把自己熟悉的模型硬套到一个按另一套逻辑构建的系统上。

第二，扩展是一个必须提前算出来的数字。第 6 章专门有 Paginating APIs（分页）和 Rate-Limiting APIs（限流）两节。假设客户需要同步 50,000 条订单，API 每页返回 100 条记录、每分钟允许 60 次请求：一次完整同步需要 500 次请求，大约 8 分 20 秒。

这还是最理想的情况。如果 5% 的请求失败需要重跑，就要多出 25 次请求，大约再多 25 秒，而且每次重试都在消耗本该留给新请求的同一份配额。现在自己改改参数，看看数字怎么变：

假设场景	请求数	最短时间
每页 100 条，每分钟 60 次请求	500	8 分 20 秒
每页 1,000 条，每分钟 60 次请求	50	50 秒
每页 100 条，每分钟 10 次请求	500	50 分钟
每页 100 条，每分钟 10 次请求，5% 重试	525	52 分 30 秒

关键在第三行。同样的数据量，仅仅配额收紧，就足以让“近实时”的承诺落空。更大的页面能缩短时间，但每次响应更重，一旦失败要重新加载的数据也更多。这些要在演示之前弄清楚，而不是演示时才发现。

第三，每次 API 版本变更，都可能让集成失效。书中专门有一章讲变更管理，练习部分一直做到在生产环境中运行 API。对 FDE 来说，阅读客户的版本历史和弃用策略，应该是第一周的任务。

集成方常犯的错误

最常见的错误是估算同步时间时忘了算重试。失败的请求同样消耗配额，仓促重跑可能让任务陷入被限流的循环，越重试越慢。

第二个错误是默认所有 API 都是 REST。如果客户通过 WebHooks 或 WebSockets 推送数据，你的架构就得接收事件，而不是轮询。这个问题判断错了，整个适配层都得重写。

第三个错误是把认证和版本管理当成一次性工作。令牌过期和版本弃用往往恰好在没人值班时引发故障，所以从第一天起就要把这两项写进运维文档。

按什么顺序读？

没必要从头读到尾。先读 API Paradigms 和安全相关内容，带着两个问题：这是哪种 API？认证怎么做、由谁授权访问？接下来读 Scaling APIs 和变更管理一章，从中找请求限制、页面大小和旧版本弃用时间表的答案。

附录 A 随时放在手边。书中把这些工作表作为 API 设计流程的模板；你可以把同一套模板当作调研清单的框架，只需把视角从设计者换成提问者。

最后做个练习：挑一个即将对接的 API，参照附录 A 把设计流程变成模板的方式，做一张一页纸的表，分四格：API 风格、安全、负载限制和版本管理。

在负载限制一格里，按上表的方式写出同步时间的计算，把重试算进去。带着这张表去参加第一次调研会议，标出客户暂时答不上来的格子。

设计最佳实践可以留到以后，等你需要对 API 提出修改建议或构建适配层时再读。开发者计划的内容，适合客户打算向合作伙伴开放 API 时，或者你转向更贴近产品的岗位时再看。

写进简历

如果只写“API 集成”，读懂别人 API 的能力很难体现出来。要具体写明你处理过哪种请求限制或哪次版本升级，结果如何，比如重新计算页面大小后，同步任务耗时变成了多少。

面试时，范式、安全、负载限制和版本管理这四个问题，是讲述一次棘手集成经历的好框架：你问了什么，发现了什么，做了什么决定。

好的开发者会读客户的 API 文档。好的 FDE 会读出写文档的人没写的东西。