如何从REST API返回错误详细信息

HTTP协议使用状态码返回错误信息。 这种功能虽然非常有用，但对于许多用例来说还是太有限了。 那么我们如何返回更详细的信息？

我们基本上可以采用两种方法：

1. 使用包含错误详细信息的专用媒体类型
2. 在使用的媒体类型中包含错误详细信息

专用错误媒体类型

这个空间至少有两个候选人：

1. HTTP API的问题详细信息是我们在某些API中使用的IETF草案，效果良好。 它将问题类型和实例都视为URI，并且是可扩展的。 JSON和XML都提供此媒体类型。
2. application / vnd.error + json仅适用于JSON媒体类型。 对我来说，它也不太完整和成熟。

专门用于错误报告的媒体类型具有可在许多REST API中重用的优势。 任何现有的用于处理它们的库都可以节省我们的精力。 我们也不必考虑如何构造错误详细信息，因为其他人已经为我们完成了所有艰苦的工作。

但是，将错误详细信息放入专用媒体类型中也会增加客户端的负担，因为客户端现在必须处理其他媒体类型。

另一个缺点与Accept标头有关。 客户端不太可能在Accept指定错误媒体类型。 通常，当我们无法Accept时，我们应该返回406或忽略Accept标头。 第一个选项是不可接受的（双关语意），第二个选项不是很优雅。

在常规媒体类型中包括错误详细信息

我们还可以设计媒体类型，以便它们允许指定错误详细信息。 在本文中，我将坚持使用三种成熟的媒体类型：Mason，Siren和UBER。

梅森使用@error属性：

{
  "@error": {
    "@id": "b2613385-a3b2-47b7-b336-a85ac405bc66",
    "@message": "There was a problem with one or more input values.",
    "@code": "INVALIDINPUT"
  }
}

现有的错误属性与HTTP API的问题详细信息兼容，并且可以扩展它们。

Siren没有特定的错误结构，但是我们可以使用现有结构轻松地对错误进行建模 ：

{
  "class": [
    "error"
  ],
  "properties": {
    "id": "b2613385-a3b2-47b7-b336-a85ac405bc66",
    "message": "There was a problem with one or more input values.",
    "code": "INVALIDINPUT"
  }
}

我们甚至可以更进一步，并使用实体来添加详细的子错误。 这对于验证错误非常有用，例如，您可以一次将所有错误报告给客户端。 我们还可以使用现有的actions属性来包含重试动作。 而且，我们可以将“问题详细信息”中的错误属性用于HTTP API。

UBER具有明确的错误结构：

{
  "uber": {
    "version": "1.0",
    "error": {
      "data": [
        { "name": "id", "value": "b2613385-a3b2-47b7-b336-a85ac405bc66" },
        { "name": "message", "value": "There was a problem with one or more input values." },
        { "name": "code", "value": "INVALIDINPUT" }
      ]
    }
  }
}

同样，我们可以为HTTP API重用“问题详细信息”中的错误属性。

结论

我的建议是使用现有媒体类型的错误结构，并使用可扩展性功能从HTTP API的问题详细信息中窃取所有好的建议。

翻译自: https://www.javacodegeeks.com/2014/11/how-to-return-error-details-from-rest-apis.html