REST API – Issues with Implementing Custom HTTP Methods

httprest

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?

Best Answer

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.

Related Topic