如何在RESTful API中处理异常以收集结果？

Question

我们正在设计一个RESTful API来返回文档集合.我们的初始实现使用HTTP状态代码来指示是否无法满足请求.这似乎是一种被广泛接受的最佳实践(例如参见此处).

我们最近遇到了一个用户正在提取1000个文档的问题.其中一个文档检索失败,因此我们返回了HTTP 500状态代码.

另一种方法是返回HTTP 200状态代码,其中有效负载具有我们能够检索的999个文档,然后是错误集合,指示失败的那个.

这种替代方法是违反RESTful原则的吗？应如何处理这种情况？除了这两种方法之外还有其他选择吗？

Answer 1

是的，我认为只要您记录您返回的数据可以包含“错误”集合，这是完全可以接受的。这意味着无论您使用什么语义媒体类型来描述此文档集合，都应该具有描述文档集合应是什么样子以及错误集合应是什么样子的文档。然后，客户可以决定如何处理这些信息。

例如，如果您将其作为 JSON 返回（仅作为示例），您可能有类似的媒体类型application/json+documents或其他内容，可能如下所示：

{ data : {
    documents: [ ... ], //document objects
    errors: [ ... ] //error objects
}

然后，您将获得描述文档外观以及错误外观的文档。在真正的 RESTful API 中，记录的是媒体类型，而不是调用，因为在真正的 RESTful API 中，只有一个端点，其他所有内容都是通过该初始端点与语义媒体类型结合“发现”的。因此，只要您记录了可能出现的错误，并描述了错误将被传递的格式，就应该没问题。

这也不是一个“例外”情况，因为在您的情况下，可以预见客户可能无法检索所有文档。因此，可以将这一事实告知客户。