REST design - An operation with multiple possible non-success payloads

Question

I'm trying to design a REST method for an 'Add person' operation that has a bunch of business rules. There are multiple possible non-success payloads (for the business purposes), requiring defined structure (to allow the consumer to parse the detail).

For 'Add a person', one of the following non-successes could happen:

1. We believe the system already has person.
   • Payload: The ID of that person
2. There are some possible matches.
   • Payload: A list of possible duplicates, and an override code to submit the record 'for sure'
3. General validation errors
   • Payload: Array of 'Error' object. (Standard across the API)

Question - Response object

If they're all to return under a single HTTP error status code, would it be right to have a varied object like:

• OverrideCode (for (1))
• PersonPossibleMatches [] (also for (1))
• PersonDuplicateId (for (2))
• ErrorList [] (for (3))

And have the consumer + documentation explain the interpretation?

Question - Response code

Is 400 (Bad Request) the correct (or correct enough) HTTP status code for this? We use it largely for the field validation (also scenario (3) - just wondering if business rule / 'intermediate state' things like this are any different.

Are there a more appropriate codes to spread the 3x scenarios over? And is it ok for the payloads to be different?

Thanks.

Answer 1

There are two aspects you need to consider

1. HTTP response code.
2. Error response payload.

Point number 1 is relatively simple. You have 400 error code for bad requests. And 409 for conflicting resources. So far simple.

Now let us consider your scenarios:

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

Design suggestion: you can send a response like below

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'

Design suggestion: In this case - you may want to use PUT to override the resource. No need to use special code.

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)

Design suggestion: Here you can simply use 400 response code and a meaningful response like the examples above.

Answer 2

This depends in part on how the operation is performed. Since you said the operation has a bunch of business rules, and the system returns a payload with an ID when the person already exists, let's assume the operation is non-idempotent due to unrelated side-effects, performed with a POST to a factory endpoint.

1. We believe the system already has person.

This is a no-brainer. As suggested by others, you should use a 409 Conflict status code, with a body describing the nature of the conflict. In this case, it seems like there's nothing else the user needs to do, and he can move forward to the next step in the workflow. If there's something he can do, it should follow a procedure similar to the next case.

2. There are some possible matches.

Assuming that the clients don't have any key to unambiguously identify a person, which seems to be your case since you're considering possible matches, here you should also use a 409 Conflict status code, with a body describing the nature of the conflict, but with instructions on how to solve it.

Some other answer suggests you to allow an overwrite parameter that could be used any time, other suggests using a PUT, but I disagree with that since there's nothing preventing a client from using the overwrite all the time, or skipping the POST and use the PUT to replace an existent close-match. Also, you may have concurrent clients trying to add or change a person that match each other, or a common existent group, which will lead to an ABA conflict.

The conflict resolution body should return a valid tag for each possible match, and the client should be instructed to resubmit the same request with the If-Match header and the collection of tags. It may be a single tag, as long as it's generated from key data from each member in the collection. This will enforce that the user first must try the request without any override. If there's a conflict the user is forced to specify the exact entities that will be overwritten, and you're protected from inconsistent updates in case someone changes the current state between the first and the second request.

If the tags don't match in the second request, meaning the state was changed by something else between them, you should fail with a 412 Precondition Failed error.

3. General validation errors

This is also a no-brainer. A 400 Bad Request detailing the error, which seems to be standard across your API.