Search code examples
restapi-designrestful-urlhttp-puthttp-patch

Different uri for PATCH vs PUT when changing uri slug

In a proper REST API implementation, imagine I'm writing an API to let the user modify a uri slug, such as changing /acme/first to be /acme/second.

Depending if I'm submitting a partial record (patch) or the whole record (put) that currently represents first, should the uri vary?

For example:

PUT /acme/second
{ [...], "current-slug": "first", "color": "blue" }

Put against the new uri because put means "this goes here."

vs.

PATCH /acme/first
{ "new-slug": "second", "color": "blue" }

Patch against the old uri because patch means "modify the thing that's here."

I suspect this is an edge case, but interesting because virtually all documentation happens to show the same uri for a put vs patch action, though obviously post is generally a different uri.

Solution

  • This is definitely a little bit of an edge case. One obvious HTTP method to do this, is actually just the HTTP MOVE method. This method comes from WebDAV, but it should work everywhere.

    MOVE /acme/first HTTP/1.1
Destination: /acme/second

    This would be my top recommendation, because it fits the problem so well.

    What's weird with either PATCH or PUT is that they are both expecting to update the resource at the target uri, but the result of the operation is more similar to DELETE because it removes the resource (and creates a new one somewhere else).

    Because of this, I would be inclined to suggest to use neither for this case. This is enough of an edge case to warrant a special POST request.

    But yea... MOVE is perfect. Any HTTP client or server that doesn't deeply understand MOVE semantics should treat it similar to POST (unsafe, not idempotent).