REST API 的试运行策略

Question

我正在为 REST API 的“试运行”操作寻找一些最佳实践。

假设我有一个将资金从账户 A 转移到账户 B 的端点。我可以像这样发起转账：

POST /transactions
{
  "amount": 1000,     // how much to transfer
  "source": "A",      // account to transfer from
  "destination": "B"  // account to transfer to
}

此操作创建一个“交易”，因此响应将是一个交易对象，其有效负载包含：

{
  "id": "txn-123",
  "amount": 1000,
  "source": "A",
  "destination": "B",
  "fees": 10,          // any fees that were charged
  "balance": 2500      // balance in source account AFTER transfer
}

我希望能够进行试运行有几个原因：

1. 确定转账是否成功（例如，如果账户 A 余额不足，转账可能会失败）
2. 事先确定适用的费用是多少

那么，“试运行”概念的最佳实践是什么？我能想到几个选项：

1. 向现有传输端点传递一个标志，以指示试运行选项。该标志可以是查询字符串、有效负载的一部分、标头等。确切的实现有待商榷，但从概念上讲，我喜欢这个，因为它提供了一个干净的接口，让您了解有关从单个执行传输的所有信息端点。
2. 专用端点专门用于执行转移试运行。这“感觉”更安全，因为您不会无意中执行破坏性操作，因为实时和空运行端点是完全分开的。另一方面，如果您可以访问生产系统，您真的应该知道自己在做什么，所以我不是一个超级粉丝。
3. 没有预演概念。只需使用一组完全不同的端点来计算费用、获取余额或任何其他有助于您推断转账结果的操作。我不喜欢这样，因为您强制客户端复制传输端点中已包含的所有逻辑。

这些是我目前对此事的看法，但我很乐意听听其他人的想法。

Answer 1

选项 3 显然是错误的。你会无缘无故地强迫客户做额外的工作。

在选项 1 和 2 之间进行选择取决于您的品味和 API 的具体情况。目前尚不清楚将/dry-run-transaction 视为与交易不同的事物是否合理。

如果您选择选项 2，请考虑将 /dry-run-transaction 设为短期资源，或者根本不保留它。这样客户就可以通过 POST 查看费用并节省存储空间。

如果您使用选项 1，我认为技术上最正确的选项是在有效负载中包含一个属性，例如 execute: false。这会将所有信息返回给客户端，并让他们使用execute: true 对事务执行 PUT 以完全按原样提交。这种方法的一个缺点是您将有一堆未执行的事务（永远？），因为人们会在看到结果后决定不执行它们。

我认为根本不讨论安全问题。如果您真的很担心，只需将 execute: false 设为选项 1 的默认值即可。

另一种方法可能是使用端点/transactions 和/transaction-results。如果您发布到/transaction，您将执行交易并获得永久交易结果的 id/result。如果你 POST 到 /transaction-results，你会得到一个没有 id 的响应和一个交易的瞬态结果集。请注意，我已经考虑了整整 20 秒，因此可能存在我没有看到的明显问题。 :-)

Answer 2

恕我直言，我认为 POST 不应该用于试运行。 Dry run 具有幂等语义，因为它不会改变系统的状态，这与 POST 相矛盾。另一方面，PUT 虽然幂等也不是一个好的选择，因为它意味着状态变化。如果我们真的想要 REST-full，那么这真的让 GET 成为唯一的选择。 因此我会创建一个单独的 REST 点：

GET /transactions/dry-run

在 URL 中嵌入{amount, source, and target}，如下所示：

GET /transactions/dry-run?amount=100&source=A&target=B