我正在设计一个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用户消费?
4条答案
按热度按时间r3i60tvu1#
对于我在前端html工作,我宁愿扁平化错误格式2。这将是很容易为我看看它,或容易目标的错误显示。
虚心听取他人意见
ulmd4ohb2#
所以你的客户端必须检查HTTP状态码,如果不是200 OK,他们必须检查错误并将JSON转换为模型对象?如果有不同类型的错误(例如BadRequest,Conflict或DB相关错误)会发生什么?
为什么不返回一个泛型
字符串
当然,这两种情况可能不会同时发生,但您仍然希望API尽可能通用,以免客户端在代码中捆绑“if“。
gz5pxeao3#
我更喜欢将错误响应作为对象的数组。错误数组可以表示每个字段的多个错误。
字符串
对于嵌套字段,我将其表示为字符串数组。
型
8ljdwjyq4#
也许它有点过时,但JSON API规范说,
Error对象必须作为JSON API文档顶层中的错误键控数组返回。
这里是一个链接