api-design - 使用 JSON API 处理具有多个属性或参数的错误

Question

JSON API 指定应单独列出属性/参数上的多个错误。处理同时涉及多个参数的单个错误的最佳方法是什么？

例如，假设端点接受 bid或 fold参数，但不是两者(它们是互斥的)。如果两个参数都提交( GET /endpoint?bid=100.00&fold=muck )，错误响应应该是什么？

两次列出错误，每个属性一次？

{
  "errors": [
    {
      "status": "400",
      "source": { "parameter": "bid" },
      "detail": "Cannot accept both 'bid' and 'fold' parameters."
    },
    {
      "status": "400",
      "source": { "parameter": "fold" },
      "detail": "Cannot accept both 'bid' and 'fold' parameters."
    }
  ]
}

结合属性？

{
  "errors": [
    {
      "status": "400",
      "source": { "parameter": ["bid", "fold"] },
      "detail": "Cannot accept both 'bid' and 'fold' parameters."
    }
  ]
}

为整个请求犯一个更高级别的错误？

{
  "errors": [
    {
      "status": "400",
      "source": { "pointer": "/data" },
      "detail": "Cannot accept both 'bid' and 'fold' parameters."
    }
  ]
}

其他方式？

Answer 1

TL;DR 版本:第一个可能是对的。

JSONAPI 规范和论坛都没有详细说明如何格式化互斥参数/数据上的错误。它确实有 this :

A server MAY choose to stop processing as soon as a problem is encountered, or it MAY continue processing and encounter multiple problems. For instance, a server might process multiple attributes and then return multiple validation problems in a single response.

重新表述您的问题，您要问的是这样的:“如果在使用第一个参数时包含禁止的第二个参数，它是单个错误还是多个错误？”

在一种观点中，这表明只有一个错误 - Cannot accept 'bid' when using 'fold' (或者相反，如果您关心排序)，并且该错误只会指向一个参数，因为在处理其中一个参数之前您不会遇到该错误。

更实际地，您正在检查您是否同时拥有它们，并且遇到错误不是因为您有一个参数然后遇到另一个，而是因为您知道您有两个参数并且现在必须处理该问题。这仍然是一个错误，指向两个参数(这是您问题的前提)。

JSONAPI spec for Error Objects表明这一点:

parameter: a string indicating which URI query parameter caused the error.

由于您必须使用 string (不是 Array )来指示错误的来源，并且错误在参数中而不是在请求正文中，您可以选择查看我上面列出的内容，将其称为仅由以下一项引起的单个错误参数，或同样归因于两个参数的相同错误，就像您在第一个示例中所做的那样。

我个人更喜欢将此视为由查询字符串中最后一个参数引起的单个错误，但您的第一个选项可能是最正确的。