关于API的一通吐槽

# 关于 API 的一篇吐槽 原文：https://dev.clintonblackburn.com/2026/10/08/a-rant-about-apis.html 过去几周，在为 Vori 自动化 onboarding 流程的过程中，我不得不与好几个不同的 API 打交道，体验堪称糟糕。这些 API 所对接的系统包括：合同渲染与电子签名收集、发票/计费系统、CRM、银行卡处理与网关，以及银行卡终端设备供应商。 它们各有各的烂法。如果这些是某个全新领域里前所未有的工作，倒也还能接受，但这些 API 对应的解决方案都已经存在十年甚至更久了。更让人恼火的是，开发者明明可以直接照抄那些已有的、更好的 API 和实践，就能做得更好，何乐而不为呢？ 以下是我的一些个人槽点。 ## 需要登录才能看的文档 如果你的 API 文档需要登录才能阅读，那你第一步就已经搞砸了。好歹你们确实写了文档，值得表扬，但为什么我非得登录才能看！？我不得不中断当前的工作流，去填一个表格或者给你的支持团队发邮件，然后等上几个小时甚至几天，就为了读一份文档！？ 我曾经就这个问题向一个团队投诉过，他们也承认需要登录的文档体验并不理想。然而，是一位高管要求做 lead 追踪的。搞什么！？我们已经是客户了。这个 lead 已经是 closed-won 了。还有什么可追踪的！ 在使用 AI agent 辅助开发时，这个问题更加严重。我更喜欢直接提供文档链接，让 agent 自行探索 schema、构建客户端、完成集成。而文档设限会打断这个流程。现在我不得不以某种方式下载文档——所幸这家还提供了 Markdown 选项——再提供给 agent。而且每个端点都得这么来一遍！ 请直接去掉文档的认证要求吧。你们浪费自己的时间和资源，只是为了让其他人也浪费时间和资源。这是一个双输的局面。 ## 没有 OpenAPI 规范 举个手。谁喜欢手写 API 客户端？如果你举手了，我不信。OpenAPI 规范已经存在 15 年了。到了今天，发布 API 却不带规范，简直就是不尊重人。你们为什么不喜欢我？为什么我要给你们送钱的时候，你们还想让我的生活变得更难？来，帮我帮你。给我一份规范，让我能生成类型化的客户端，把精力放在自己的业务上。 哦，你说"我们这里有个 Postman collection"？好吧，聊胜于无，但现在我还得想办法把它转换成 OpenAPI 规范。我们为什么要浪费时间用一个更差的格式？把好东西给我！ ## 没有自助式的凭证签发 这和文档设限的问题类似。API 需要凭证。废话。请让我自己生成/轮换凭证。为什么我要等*好几个星期*，等 IT 团队来生成凭证、翻个开关之类的？总有意外发生。有时候我们需要轮换凭证。别让我为了一个潜在的安全事件去提交支持工单！这意味着一个周六冒出来的问题，大概要等到周一中午有人看到工单才会被修复。 ## 凭证的身份错乱 好吧，你们做了自助式凭证签发。不错。但是等等！现在你告诉我，这个凭证和创建它的人的身份绑定在一起。意思是……所有日志都关联到那个人，导致无法区分我们后端应用发出的 API 调用和那个人在你们 Web 应用里的操作？意思是……只有那个人才能轮换凭证，而我们不能简单地通过共享凭证来规避这个问题，因为你们的应用强制要求 SSO，我们必须在账号共享这条线上画出底线？意思是……停用那个人的账号几乎肯定会引发事故？ 我正在主动迁移掉一家这样做的电子签名供应商，因为*我*就是那个设置账户的人，而我目前正在休假，导致其他人看不到合同，因为*当然*我希望所有发给杂货商的合同都关联到我的账户！我对供应商的考察清单又增加了一项。 ## Webhook 的"验证" Webhook 对于构建准实时的工作流非常棒。我爱它。但我不爱上面提到的那家电子签名供应商，他们在保存 Webhook 端点之前要先进行"验证"。"这是什么验证"，你问。很简单（也很蠢）：供应商向端点发送一个 payload，只有当端点返回成功响应时，才会保存新的 Webhook 配置。 任何 Webhook 集成指南的第一部分都在讲安全。*永远*要用共享密钥验证 payload，并拒绝无效的 payload 而不进行处理。然而……没有共享密钥就没法验证，而供应商在端点被验证可用之前不会给我共享密钥。🙃 这就是为一个本不该存在的问题所想出来的荒谬变通方案： 1. 创建一个 Webhook，指向一个已知的、对 POST 总是返回 200 响应的 URL，例如 https://echo.free.beeceptor.com。 2. 将共享密钥存储在密钥管理器中。 3. 更新 Webhook，把 URL 改为正确的地址。 4. 祈祷你永远不需要轮换密钥。 我就此提交了支持工单，回复的人完全不理解这为什么是一个有问题的流程。不过他们确实理解我正在迁移他们的产品，于是突然想跟我聊聊，想获取反馈。 ## 总结一下这些吐槽 值得一提的是，我甚至还没聊到 API 的 schema 和资源设计。大多数公司在这方面做得不错，RESTful API 使用了可理解的名词和动词来定义业务概念和操作。而一些老牌支付公司，尽管有超过 15 年的时间可以直接抄 Stripe，不知为何在这方面依然挣扎。说真的，直接抄 Stripe API 就行了。我们花了很多时间和精力来构建它。它很好。拿去用吧。 我还是很高兴有人在做 API，即便开发者体验烂得不行。我们大约用四周时间消除了一段 40 多个步骤的流程。当然，agent 用大概 4 个小时就写完了代码，四周中的大部分时间都在等凭证，但进步就是进步。