外部API关闭时的REST API状态-最佳实践

Question

当涉及到从REST API返回错误时，我正在寻找关于良好实践的指导。我正在开发一个新的API，这样我就可以把它带到任何方向。

在我的例子中，客户端调用我的API，而API在内部调用一些外部API。如果成功，没问题，但如果有来自远端(外部云API)的错误响应，我不确定这类服务的行业标准是什么。我目前正在考虑返回200OK，然后返回一个json有效负载，它详细说明了外部API错误。

那么，行业建议是什么呢？良好实践(请解释原因！)另外，从客户端pov的角度来看，REST API中的哪种错误处理使客户端代码的工作更轻松？

Answer 1

您询问的故障是在服务本身的内部发生的故障，尽管它具有外部依赖项，因此5XX状态代码范围是正确的选择。503服务不可用看起来非常适合您所描述的情况。

5XX代码用于告诉客户端，尽管请求是正常的，但服务器在满足请求时遇到了某种问题。另一方面，

4XX代码用于告诉客户端它在请求中做了一些错误的事情(并且服务器是正常的，谢谢)。Sections 10.4 and 10.5 of the HTTP 1.1 spec解释4XX和5XX代码的不同用途。

Answer 2

我们的同事已经提供了有关HTTP状态代码的链接/解释，因此您应该学习它们，并找到最适合您的情况。

假设您已经学习了状态代码，我将更多地关注影响您的决策的因素。

基本上，您应该了解客户端调用您的API时触发的流的业务含义是什么。客户端对您正在使用的外部云API一无所知，也不真正关心它是否工作，客户端使用您的应用程序。

如果是这样，当远程系统返回某种类型的错误时(是的，不同的错误状态应该为您提供有关远程系统问题的线索)，这是您关于如何处理此错误的业务决策，并且根据此决策，您可能希望在与客户端的交互中以不同的方式“行为”。

下面是一些示例：

1. 您知道远程系统极少崩溃。但是一旦它不可用，你的系统就不能正常工作。在这种情况下，如果调用失败，您可以考虑重试对远程系统的调用。如果你仍然不走运，那就返回一些错误状态。可能像5xapi这样的东西你知道远程客户端提供的数据并不是真正重要的，另一方面，当客户端调用你的

时，最好提供“一些”，即使它不是真正最新的也比什么都没有好。考虑一下通过某个客户端id提供“推荐电影”的远程系统。您正在构建一个门户(netflix风格)。如果这个推荐的电影服务由于某种原因而关闭，那么整个门户页面都会失效是没有意义的(想想糟糕的用户体验吧)。在这种情况下，您可能希望“预缓存”一些通用电影列表，并将其用作远程服务失败时的备用方法。在这种情况下，显然你在任何情况下都应该返回2XX状态。

1. 更高级的架构。您知道远程服务经常失败，并且您可以在其关闭时继续工作。在这种情况下，您可能希望选择与客户端交互的“异步”样式。例如:客户端调用您的rest，您立即使用“已接受”状态代码进行响应(202)。您可以将此id与状态一起保存在某个数据库中，以便当用户“通过票证id请求票证的状态”时，您将能够查询数据库。关键是你要马上回来。然后，您可能希望将消息与任务一起发送到某个消息传递系统，一旦消费者选择了该消息，它就会被处理，数据库也会被更新。只要远程服务失败，消息就会返回到队列，但仍处于“未处理”状态(通常消息传递系统可以实现此行为)。现在，在某个时间点，远程系统开始响应，所有消息都会得到处理。现在他们在数据库中的状态是“完成”。所以它由客户来询问“发生了什么”/or你可以用web套接字或其他东西实现一些推送模型(在这种情况下，它不再是REST风格的通信)。但重点是，在某个时间点，客户端将收到"OK，我们完成了票证ID“(状态200)。在这种情况下，客户端可以调用一个特殊的端点，并使用存储在DB中的结果(同样是状态200)

归根结底，正如你所看到的，HTTP返回代码只是一个指示器，但它取决于你如何组织与客户端的互连过程，相关的HTTP状态将由你的决定决定。

Answer 3

我会使用503 -服务不可用-作为错误。原因：

• 这是考虑如果没有外部接口的响应，接口操作无法完成的情况。这类似于我的数据库没有响应。因此，在外部服务重新上线之前，我的API不可用。
• 作为API客户端，我并不关心API服务器内部是否会调用其他API。我只关心API服务器的结果。因此，我是否是代理对客户端来说并不重要-因此，我将避免502 (错误网关)和504 (网关超时)。
• 正如@developerjack所建议的，我还建议-“包括一个HTTP头，这样你的Retry-After客户端就知道在X次之后重试不会给你发送垃圾邮件。这意味着你的错误流量更少，对客户端的请求规划也更好。”