Are there any problems with implementing custom HTTP methods?

Question

We have a URL in the following format

/instance/{instanceType}/{instanceId}

You can call it with the standard HTTP methods: POST, GET, DELETE, PUT. However, there are a few more actions that we take on it such as "Save as draft" or "Curate"

We thought we could just use custom HTTP methods like: DRAFT, VALIDATE, CURATE

I think this is acceptable since the standards say

"The set of common methods for HTTP/1.1 is defined below. Although this set can be expanded, additional methods cannot be assumed to share the same semantics for separately extended clients and servers."

And tools like WebDav create some of their own extensions.

Are there problems someone has run into with custom methods? I'm thinking of proxy servers and firewalls but any other areas of concern are welcome. Should I stay on the safe side and just have a URL parameter like action=validate|curate|draft?

Answer 1

One of the fundamental constraints of HTTP and the central design feature of REST is a uniform interface provided by (among other things) a small, fixed set of methods that apply universally to all resources. The uniform interface constraint has a number of upsides and downsides. I'm quoting from Fielding liberally here.

A uniform interface:

• is simpler.
• decouples implementations from the services that they provide.
• allows a layered architecture, including things like HTTP load balancers (nginx) and caches (varnish).

On the other hand, a uniform interface:

• degrades efficiency, because information is transferred in a standardized form rather than one which is specific to an application's needs.

The tradeoffs are "designed for the common case of the Web" and have allowed a large ecosystem to be built which provides solutions to many of the common problems in web architectures. Adhering to a uniform interface will allow your system to benefit from this ecosystem while breaking it will make it that difficult. You might want to use a load balancer like nginx but now you can only use a load balancer that understands DRAFT and CURATE. You might want to use an HTTP cache layer like Varnish but now you can only use an HTTP cache layer that understands DRAFT and CURATE. You might want to ask someone for help troubleshooting a server failure but no one else knows the semantics for a CURATE request. It may be difficult to change your preferred client or server libraries to understand and correctly implement the new methods. And so on.

The correct^* way to represent this is as a state transformation on the resource (or related resources). You don't DRAFT a post, you transform its draft state to true or you create a draft resource that contains the changes and links to previous draft versions. You don't CURATE a post, you transform its curated state to true or create a curation resource that links the post with the user that curated it.

^{* Correct in that it most closely follows the REST architectural principles.}

Answer 2

I think custom HTTP method is the very best way to implement entity actions. Adding the action to the entity body (POST) doesn't seems right, it's not part of your entity (although the result might be saved in it). Also, using the custom HTTP methods proxies could determine their actions without the need of parsing the entity body.

It's like CRUD, you'd always want to implement those, but also you have your own specific set of actions (per enitity). I really don't see what would be the problem extending those.

Also @Rein Henrichs "You don't DRAFT a post, you transform its draft state to true or you create a draft resource" seems false to me. A drafts property would be used for persistent saving the state, not for making the transformation. Actions don't even necessarily result in a 'state', or be saved in a property. Creating a seperate entity for each state/transformation seems even more fuzzy.. try to maintain the same reference (URI) to the enity.

Answer 3

I would prefer to design these as subresources, onto which you perform a POST request.

Consider you have a resource at /instance/type/1, I would have the representation of that resource convey a couple of links to 'actions' that can be performed on the resource, such as /instance/type/1/draft and /instance/type/1/curate. In JSON, this could be as simple as:

{
    "some property":"the usual value",
    "state": "we can still inform the client about the current state",
    "draft": "http://server/instance/type/1/draft",
    "curate": "http://server/instance/type/1/curate"
}

This allows the client to be very explicit about what needs to happen, during the POST request to the link provided by the curate member. The resource posted there could include arguments that detail the event that would, perhaps, inflict a state transition.

Going with the 'naive' approach of moving between the possible states on a resource has the disadvantage of not capturing what events led to these transitions.

State transitions usually occur in response to specific events, and I'd rather capture those events than let the client decide that something is now in a specific 'state'. It also makes validation a lot harder. Plus, you wouldn't be able to capture any 'arguments' unless you describe those in the state itself as well. And then it gets all icky when some code changes those without real state transition, and the validation required, and the whole thing quickly becomes a mess.