API与集成

这个分类涵盖什么

这里有四项相关的工作。手工构建和测试请求。为接口编写文档，方便他人使用。在多个服务前放置一个网关，让密钥、速率限制、配额和版本在各处表现一致。在本来就没有设计成可以互通的产品之间搬运数据。

前三项面向发布API的团队。第四项面向把所购工具拼接起来的人。两类受众都来到这份榜单，所以这里的产品看起来互不相像。

完全可视化、不涉及代码的自动化归入无代码与自动化。对线上服务的告警属于监控。

客户端，以及如今它们的区别

每个客户端都是发送请求并显示响应。差别在更深处。

首先是环境处理：本地、预发布、生产，以及同事在笔记本上运行的任何环境，切换干净利落，无需任何人手动改网址。其次是脚本，这样令牌可以在请求之前获取，而不是每天早上粘贴。再次是测试断言，让一个集合变成构建服务器可以运行的东西。

协作是意见分歧所在。云同步很方便，但会把您的请求历史放在别人的服务器上。基于文件的工具把集合放在代码旁边的仓库里，因此变更可以像其他变更一样评审，也不会有工作区随离职员工一起带走。

无论哪种方式，都要问清机密信息存放在哪里。写进导出集合里的密钥，是进入公开代码仓库的标准路径。

不会腐烂的文档

手写文档在一个季度内就会过时。唯一能存活的做法，是由与代码放在一起的规范生成，并在代码合并时重建。

检查三件事：产品是否无需转换步骤就能读取您的规范格式，示例能否在页面上直接运行，以及旧版本是否继续发布，供仍在使用的人查阅。

变更日志比设计更重要。使用者需要知道什么改坏了、何时改坏的，再多的样式也无法替代这一点。

网关，以及什么时候值得上

单个服务很少需要网关。当身份验证、速率限制、配额和版本管理必须在多个服务间表现一致时，这种需求才会出现。

到那时要问的问题是：它运行在哪里、增加多少延迟，限制如何定义、触发时调用方看到什么，密钥能否在不停机的情况下轮换，以及日志里有什么。任何终结流量的东西本身就是可用性风险，所以要问问网关自己出问题的那天会发生什么。

定价计量的是什么

• 客户端和文档类产品按席位，有时只读的审阅者免费。
• 集成平台按任务或运行次数，按步骤而不是按工作流计数。
• 网关按调用量或带宽，缓存内容另有费率。
• 运行历史的保留期限，入门方案很短，而且恰恰在您需要它的时候很短。
• 连接器，高级的那些放在比报价方案高一档的位置。

任务计价在签约前值得算一笔账。一个六个步骤、每十分钟运行一次的工作流，每月不是一个任务，这个数字让不少团队吃了惊。其他分类里同样性质的意外，汇总在定价页隐藏了什么。

测试什么

从头到尾重建一个您已经在运行的真实集成，包括对方返回错误的那部分。

观察工具如何处理重试、重复投递、停滞的第三方，以及缺少字段的载荷。做得好的产品允许您在修复原因后重放失败的运行。差一些的会悄无声息地丢掉它，直到客户发现之前不会告诉您任何事。

然后检查退出路径。集合、规范和工作流定义应当可以导出为您能读懂的文件。任何锁在工作区里的东西，都是您要做两遍的工作。

文档、版本管理与留住使用者

有用户的接口就是一份承诺，这个分类里大部分难点，都来自在不违背承诺的前提下修改接口。

在第一个外部使用者到来之前就定下版本管理方案，因为事后补救意味着要求所有人同时修改。无论采用什么方案，都要公布改了什么、何时改的，并给出以月而不是以周计算的弃用期。

错误和成功一样值得重视。一条说明出了什么问题、哪个字段导致、下一步该做什么的响应，减少的支持请求比任何篇幅的文字都多。

然后以新手的视角读一遍您自己的文档。最快的改进通常是在页面顶部放一个能运行的示例，而不是一张参考表。