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

Question

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

我们最近遇到了一个问题，即用户拉取了 1000 个文档。其中一个文档检索失败，因此我们返回了 HTTP 500 状态代码。

另一种方法是返回一个 HTTP 200 状态代码，其负载包含我们能够检索的 999 个文档，然后是一个错误集合，指示失败的文档。

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

Answer 1

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

例如，如果您将其作为 JSON 返回(只是一个示例)，则您可能有类似 application/json+documents 的媒体类型。或类似的东西:

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

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

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