不抽象：Increase API 设计原则

原文：Increase - 2024.04.26

（注：Increase 是一家提供金融技术服务的公司。）

API 资源是 API 的实体或对象。决定如何为这些实体命名和建模可以说是设计 API 最难也是最重要的部分。您所公开的资源组织了用户对您的产品如何工作以及它能做什么的心智模型。在 Increase，我们的团队采用了一项名为“不抽象”的原则来帮助我们。那么，这个原则是什么呢？

我们团队的大部分成员都来自 Stripe，在设计 API 时，我们考虑了在 Stripe 取得成功的相同价值观。Stripe 擅长在他们的 API 中进行抽象设计 —— 将复杂领域的基本特征提取出来，使用户能够轻松理解和操作。在他们的案例中，最显著的是将许多不同网络的支付建模到一个名为 PaymentIntent 的 API 资源中。例如，Visa 和 Mastercard 在发起退款的原因代码上存在细微差别，但 Stripe 将这些代码合并到一个枚举中，这样用户就不必分别考虑这两个支付网络。

这样做是有道理的，因为 Stripe 的许多用户都是早期创业公司，开发的产品与支付完全无关。他们不一定了解或需要了解信用卡的细微差别。他们希望快速集成 Stripe，继续开发自己的产品，而不再考虑支付问题。

“对 Increase 的用户来说，试图隐藏这些网络底层的复杂性会让他们感到烦恼，而不是简化他们的生活。”

Increase 的用户并非如此。他们通常对支付网络有深入的了解，一直在思考金融技术问题，之所以选择我们，是因为我们有直接的网络连接和深度集成，可以帮助他们构建支付网络。他们希望确切知道 FedACH 窗口何时关闭，转账何时到账。他们知道，在 ACH 转账上设置不同的 Standard Entry Class code 会导致不同的返回时间。试图隐藏这些网络的潜在复杂性（例如，通过单一 API 资源对 ACH 转账和电汇进行建模）会让他们感到烦恼，而不是简化他们的生活。

（注：ACH 是美国主要使用的电子支付系统。FedACH 则是美联储提供的 ACH 服务。）

与这些用户的早期对话帮助我们在构建第一版 API 时明确了“不抽象”原则。下面举例说明这种思维方式对 API 设计的影响：

现实的（Real-world）命名

我们倾向于使用底层网络的词汇，而不是自己为 API 资源及其属性命名。例如，在通过 Increase API 进行 ACH 转账时，我们公开的参数就是以 Nacha 规范中的字段命名的。

（注：Nacha 规范用于指导金融机构如何正确、安全地使用 ACH 网络进行电子交易。）

不可变性

与使用网络术语的方式类似，我们也尝试根据现实世界中的事件（如采取的行动或发送的消息）来为我们的资源建模。这使得我们更多的 API 资源是不可变的。对这种 API 来说，一种行之有效的方法是将这些不可变资源（例如，作为 ACH 转账生命周期的一部分可以发送的所有网络消息）集中起来，并将它们归类到一个状态机“生命周期对象”中。例如，我们 API 中的 ach_transfer 对象有一个名为 status 的字段，它会随着时间的推移而变化，还有几个不可变的子对象，会随着转账在其生命周期中的移动而被创建。一个新创建的 ach_transfer 对象看起来像这样：

{"id": "ach_transfer_abc123","created_at": "2024-04-24T00:00:00+00:00","amount": 1000,"status": "pending_approval","approval": null,"submission": null,"acknowledgement": null// 为了清晰起见，这里省略了其他字段
}

在同一笔转账通过我们的管道并提交给 FedACH 后，它看起来像这样：

{"id": "ach_transfer_abc123","created_at": "2024-04-24T00:00:00+00:00","amount": 1000,"status": "submitted",// 不可变的，当转账被批准时填充"approval": {"approved_by": "[e-mail]","approved_at": "2024-04-24T01:00:00+00:00"},// 不可变的，当转账被提交时填充"submission": {"trace_number": "058349238292834","submitted_at": "2024-04-24T02:00:00+00:00"},// 不可变的，当转账被确认时填充"acknowledgement": {"acknowledged_at": "2024-04-24T03:00:00+00:00"}// 为了清晰起见，这里省略了其他字段
}

按用例分离资源

对于给定的 API 资源，如果用户可以在该资源的不同实例上执行的操作集差异很大，我们倾向于将其拆分为多个资源。例如，您可以对发起的 ACH 转账执行的操作集与接收的 ACH 转账执行的操作集不同（实际上完全相反），因此我们将其分为 ach_transfer 和 inbound_ach_transfer 资源。

---

这种方法可能会使我们的 API 更为冗长，乍看之下令人生畏–我们的文档页面左侧有很多资源！不过，我们认为从长远来看，这种方法更具有前瞻性和可预测性。

重要的是，我们的工程团队已经承诺采用这种方法。设计一个复杂的 API 需要数年的时间，这期间会不断做出小的增量决策。预先承诺“不抽象”原则减轻了这些决策的认知负担。例如，在向美联储发送电汇时，有一个名为Input Message Accountability Data 的必填字段，它是该电汇的全球唯一 ID。在构建支持电汇的功能时，API 抽象程度高的的工程师可能需要深思熟虑如何以“用户友好”的方式命名这个字段–trace_number、reference_number、id…等等。在 Increase，这位假设的工程师会将字段命名为 input_message_accountability_data，然后继续工作。当 Increase 的用户第一次遇到这个字段时，虽然一开始可能不是最容易识别的名称，但这可以帮助他们立即了解这个字段是如何映射到底层系统的。

“不抽象”原则并不适合每个 API，但考虑适合开发人员集成 API 的抽象程度是一项有价值的工作。这将取决于开发人员在您的产品领域的工作经验水平，以及他们为集成所投入的精力等。如果您正在构建一个抽象程度高的 API，那么在添加新功能之前，请深思熟虑。如果您要构建的是抽象程度低的 API，则应致力于此，并抵制在出现新功能时添加抽象功能的诱惑。