Question

我正在设计一个RESTful API，并想知道验证错误消息的最佳格式是什么。

例如，我的帐户创建端点接受JSON对象：

user: {
  first_name: string,
  last_name: string,
  address: {
    street: string,
    city: string,
    zip_code: string
  }
}

我的回复将采用以下格式：

{
    code: 400,  // HTTP code
    message: "Validation failed",  // general message
    type: "validation_failed",  // there are other types of errors as well
    errors: WHAT_DO_I_SHOW_HERE
}

我有几种验证错误消息的选择：

格式1

errors: {
  last_name: "First name is required",
  address: {
    zip_code: "ZIP code is invalid"
  }
}

或压缩错误，如格式2

errors: {
  last_name: "First name is required",
  "address.city": "City is required",
  "address.zip_code": "ZIP code is invalid"
}

或使用数组，其中每个元素都可以包含字段名称，错误代码，错误消息，嵌套错误等。

errors: [
  {
    field: "first_name",
    message: "First name is required",
  },
  {
    field: "address",
    errors: [
      {
        field: "zip_code",
        message: "ZIP code is invalid"
      }
    ]
  }
]

或

errors: [
  {
    field: "first_name",
    message: "First name is required",
  },
  {
    field: "address.zip_code",
    message: "ZIP code is invalid"
  }
]

显然，阵列格式更灵活，因为字段名称是可选的，因此它可以容纳与多个字段的组合相关的错误（例如，时间间隔的结束时间必须在开始时间之后）。但我的问题是，API用户更容易使用哪一个？

Answer 1

对于我在前端html工作，我宁愿扁平化错误格式2.我很容易调查它，或者很容易找出错误来显示。

公开听取他人意见

Answer 2

因此，您的客户必须检查HTTP状态代码，如果它不是200，那么他们是否必须查看错误并将该JSON反序列化为模型对象？如果出现不同类型的错误（例如BadRequest，Conflict或DB相关错误），会发生什么？

为什么不返回通用

errors: [
  {
    type: "ValidationError", // or an int value from an Enum
    message: "First name is required",
  },
  {
    type: "DBError",
    message: "Connection not found" // you might want to say something more generic here, but at the same time if you don't treat it at all it will bubble up as a 500 internal server error
  }
]

当然，两者可能不会同时发生，但是，您仍然希望您的API尽可能通用，以免您的客户捆绑在一起＃34;如果在他们的代码中。

Answer 3

我希望将错误响应作为对象的数组。错误数组可以表示每个字段的多个错误。

errors: [
    {
        field: "name",
        message: "name should be at least 4 characters"
    },
    {
        field: "name",
        message: "name should not begin with a dollar sign ($)"
    },
    {
        // other fields
    }
]

对于嵌套字段，我将其表示为字符串数组。

errors: [
  {
    field: ["address", "zip_code"],
    message: "ZIP code is invalid"
  }
]

Answer 4

也许有点过时，但是JSON API规范说

错误对象必须以JSON API文档顶层中的错误为键的数组形式返回。

Here is a link

REST API中的验证错误响应

4 个答案: