Response code 409 instead of 404 when PATCHing against nonexisting resource?

[bschaeublin]

The guidline mentions this:

If a service does not support UPSERT, then a PATCH call against a resource that does not exist MUST result in an HTTP "409 Conflict" error.

In the refered RFC 5789 there is this:

Resource not found: Can be specified with a 404 (Not Found) status
code when the client attempted to apply a patch document to a non-
existent resource, but the patch document chosen cannot be applied
to a non-existent resource.

I think this should be clarified, and the following should be added (according to RFC 5789):

Conflicting state: Can be specified with a 409 (Conflict) status
code when the request cannot be applied given the state of the
resource. For example, if the client attempted to apply a
structural modification and the structures assumed to exist did
not exist (with XML, a patch might specify changing element 'foo'
to element 'bar' but element 'foo' might not exist).

[RobDolinMS]

Thanks for submitting @maerlin. Tagging @garethj-msft and @darrelmiller for opinions

[darrelmiller]

I'm not sure why the decision was made to use 409 to indicate that no resource exists and the server can't create it. I would have expected a 404, personally. Maybe @cleemullins knows. I know sometimes people don't like returning 404 because they are concerned that it will mislead a developer into thinking some other part of the URL contains an error, rather than it being an unsupported operation.

However, I don't think the choice of the API Guidelines is actually in violation of RFC 5789. It is quite reasonable to assume that try to patch a resource that does not exist "cannot be applied given the state of the resource".

[bschaeublin]

@darrelmiller Thank you for your thoughts !I would like to make a few further remarks.

Part 1

I know sometimes people don't like returning 404 because they are concerned that it will mislead a developer into thinking some other part of the URL contains an error, rather than it being an unsupported operation.

If you patch a ressource, that does not exist, like this:
PATCH /api/notes/{guid}

Then it would be a part of the url containing an error, because the object with this guid does not exist.

Part 2

However, I don't think the choice of the API Guidelines is actually in violation of RFC 5789. It is quite reasonable to assume that try to patch a resource that does not exist "cannot be applied given the state of the resource".

But if you patch a path or property that does not exist, like in this example /notetitle should be /title:

PATCH /api/notes/{Guid}'
[
{"op": "replace", "path": "/notetitle", "value": "testnote"}
]

In this case RFC 5789 mentions to return an 409.
So, in my opinion, there should be a difference when the whole ressource was not found, or if just a part/property/path of the ressource is unknown or has changed.

[darrelmiller]

@maerlin I think both cases are debatable and regardless of which side of the debate that you are on, I don't think there are any significant negative side effects.

I would prefer to see a 404 in the first case and a 409 in the second, but mostly likely we would need a payload to describe exactly where the conflict arose anyway, and it is easy to explain to the consumer what the problem in that description.

Off the top of my head I can't imagine a case where my client would need to take different actions based on these two different status codes in this scenario.