REST 设计 - 具有多个可能的非成功负载的操作

Question

我正在尝试为具有大量业务规则的“添加人员”操作设计一个 REST 方法。有多种可能的非成功负载(出于业务目的)，需要定义的结构(以允许消费者解析细节)。

对于“添加一个人”，可能会发生以下不成功之一:

1. 我们相信系统已经有人了。
   • 有效载荷:该人的 ID
2. 有一些可能的匹配项。
   • 有效负载:可能重复项的列表，以及用于“确定”提交记录的覆盖代码
3. 一般验证错误
   • 有效载荷:“错误”对象数组。 (API 标准)

问题 - 响应对象

如果它们都在单个 HTTP 错误状态代码下返回，那么使用不同的对象是否正确:

• OverrideCode(对于(1))
• PersonPossibleMatches [](也适用于 (1))
• PersonDuplicateId(对于 (2))
• ErrorList [](对于(3))

消费者+文档是否解释了解释？

问题 - 响应代码

400(错误请求)是否是正确(或足够正确)的 HTTP 状态代码？我们主要将它用于现场验证(也是场景 (3) - 只是想知道像这样的业务规则/“中间状态”是否有任何不同。

是否有更合适的代码来扩展 3x 场景？有效负载可以不同吗？

谢谢。

Answer 1

有两个方面你需要考虑

1. HTTP 响应代码。
2. 错误响应负载。

第 1 点相对简单。您有错误请求的 400 错误代码。 409 表示资源冲突。到目前为止很简单。

现在让我们考虑您的场景:

1. We believe the system already has person. Payload: The ID of that person

设计建议:您可以发送如下响应

Response code: 409

{
    "error_code": "resource_exists",
    "error_description": "Resource person with ID XXX already exists"
    "debug_info": "",
    "link" : [
        {
            "href": "http://host-name/persons/123456",
            "rel": "person"
        }
    ]
}




2. There are some possible matches.
    Payload: A list of possible duplicates, and an override code to submit the record 'for sure'

设计建议:在这种情况下 - 您可能希望使用 PUT 来覆盖资源。无需使用特殊代码。

Response Code: 400
{
    "error_code": "potential_duplicates",
    "error_description": "Potentially the resource is duplicate of one of the following. Please use PUT with the resource ID to update"
    "debug_info": "",
    "link" : [
        {
            "href": "http://host-name/persons/234",
            "rel": "person"
        },
                {
            "href": "http://host-name/persons/456",
            "rel": "person"
        },
        {
            "href": "http://host-name/persons/789",
            "rel": "person"
        }
    ]
}

1. General validation errors Payload: Array of 'Error' object. (Standard across the API)

设计建议:这里可以简单的使用400响应码和像上面的例子一样有意义的响应。