公开异步系统的公共 API

Question

我们现在正致力于向外部世界公开我们的生产 Rest API，以便将不同的 3rd 方集成到我们的系统中。 我们遇到的问题之一是，由于高规模和性能的原因，许多API 命令都是异步处理的，因此无法将结果直接返回给调用者。

例如 - deliver order 命令可能需要一些时间才能完成，这意味着：

1. 在响应正文中，我们无法返回传递文件​​，因为它们尚未处理，但只有 202 accepted 状态。
2. 我们不能保证在下次致电 get deliveries API 时这些都准备好了。

对于如何解决这个异步问题，我们几乎没有什么想法，但我们想知道是否有一些用于异步系统公开 API 的最佳实践。其中大多数是 202 状态码，或者可能是 command ID，它们可以轮询/注册到 webhook，这似乎很潮。

使用这些 API 的客户是否可以理解他们执行的操作需要时间才能发生？并且同步响应并不总是可用？

Answer 1

有一些易于理解的模式用于通过 HTTP API 公开长时间运行的异步操作。你如何去做取决于你的具体要求，这里有一些注意事项：

1. 短轮询。在此模式中，您有一个“启动”HTTP API，它返回 HTTP 202 和异步操作的唯一标识符。然后，您有一个“查询”HTTP API，它接受该唯一标识符并以操作状态进行响应。由调用者决定调用“查询”API 的频率，但一般来说，在异步操作完成和调用者发现它的那一刻之间会有延迟。这种模式的一个例子是 AWS 的 Cloud Watch Logs Insigts StartQuery 和 GetQueryResults API。

2. 长轮询。在此模式中，“查询”HTTP API 是一个 HTTP 长轮询，这意味着服务器将保持打开状态，直到操作完成或经过最长时间（通常少于 45 秒）。如果 HTTP 长轮询在异步操作完成之前返回，调用者应该立即发出一个新的“查询”操作。这种模式通常对您来说实现起来更复杂，并且更占用资源（保持 TCP 连接打开），但会降低调用者发现操作竞争的延迟。

3. 网络套接字。在此模式中，调用者创建一个持久的 webhook 连接来启动异步操作并等待其完成。这在通知调用者完成时提供了最低的延迟，但超出了常规 HTTP 的 RPC 语义的“面包和黄油”，因此需要调用者方面更复杂一些。

4. 网络钩子。一些系统选择公开 webhook 以通知客户异步发生的重要事件。根据您的异步操作的持续时间，这可能是使用正确的模式。例如，Stripe uses webhooks a lot 通知客户付款状态的变化。

除了处理异步操作，there is a number of other considerations when exposing HTTP APIs from your system 的想法是帮助人们与您的应用程序集成。