Question

.NET中使用Web API的最佳做法是什么？特别是Web REST API。当异常发生时，REST API是否应该在响应正文中返回异常？

我肯定会返回500或类似的HTTP状态。但是当我用这个错误代码回复时，最佳做法是什么？或者更好的是关于这个的规范或REST API是什么？

返回异常（我做的）
返回空响应体？（是的，但我们失去了有助于调试的信息）
返回一个空的默认JSON对象？（我发现这令人困惑）
别的什么？

Answer 1

返回异常（我做的） - ＆GT;您不应该按原样返回异常，因为：1）它可能包含您不希望向REST API用户公开的信息。例如，在出现IO异常时考虑文件路径，或者在出现sql异常时考虑sql server信息，依此类推。 2）您将发送REST API客户端不需要的信息，从而浪费带宽并序列化不必要的信息。

返回空响应体？ - ＆GT;没有。

返回一个空的默认JSON对象？ - ＆GT;否。

其他什么？ - ＆GT;返回一个非常具体的错误消息（以及您认为可能对正在集成REST API以解决该错误的开发人员有帮助的任何其他信息，或者如果您提供该错误消息，则可以跟踪该错误。毕竟，您将必须在某个时候调查一些问题，所以要确保你传递的信息足以让你知道出了什么问题。

Answer 2

我有这个建议。

错误需要由应用程序（API）中的某个过滤器处理。此过滤器将收到意外错误，在http状态代码等于500的JSON中转换错误。

返回的错误需要具有相同的JSON格式，如下所示：

{
    code: 12321312,
    message: "A fatal error occurred",
    details: "An unexpected information was passed as parameter to the API."
}

错误格式需要提供信息。当您在Filter中收到错误时，可以使用生成的代码（错误代码，如UUID）将错误保存在数据库中，并在JSON中返回code。要拥有一个不错的API，使用错误代码将是一个很好的功能，可以帮助您识别问题。

Answer 3

总的来说，是的，您应该在响应正文中包含异常的表示。例外将是对错误之处的最佳解释，并且对于帮助用户纠正任何出错的内容将是最有用的。对于所有错误，我建议使用400的响应码，但是400范围内的任何数字都是可以接受的。

我做了一些研究，发现最常见/标准使用这种形式的JSON结构：

{
   "error": {
      "code": "400",
      "message": "main error message here",
      "target": "approx what the error came from",
      "details": [
         {
            "code": "23-098a",
            "message": "Disk drive has frozen up again.  It needs to be replaced",
            "target": "not sure what the target is"
         }
      ],
      "innererror": {
         "trace": [ ... ],
         "context": [ ... ]
      }
   }
}

其中许多是可选的，但是如果您需要它们的话。这种结构的重要之处在于，错误是在对象中的“错误”成员下描述的。

这是OASIS数据标准OASIS OData提出的格式，似乎是目前最标准的选择，但是目前似乎没有任何标准的采用率很高。

有关详细信息，请参见我在Error Handling in JSON REST API上的博客文章

REST API是否应该在响应正文中返回异常？

3 个答案: