In Phil Sturgeon’s article Understanding REST and RPC for HTTP APIs, he makes the assertion that the following URL is not technically RESTful.
POST /trips/123/start I have made a habit of countering these assertions of “non-restfulness” with the following question:
Can you point to the REST constraint that is violated and the negative system effects due to the violation of that constraint?
I don’t believe any REST constraint is being violated by that URL.
Machines don’t care what your URL says
As far as I understand, clients in RESTful systems treat URLs as opaque identifiers and therefore there are absolutely no negative system effects of a verb appearing in a URL.
Obviously having a URL that contains a verb that contradicts the method used, would be confusing to a developer, but that is a documentation issue. e.g.
GET /deleteThing
that safely returns a thing could be RESTful but is very misleading. But, GET /deleteThing
that deletes an object would violate the uniform interface constraint for HTTP requests and is therefore not RESTful. The server’s behaviour is inconsistent with the GET HTTP method. That’s bad. The word delete in the URL is unfortunate.
RPC is a client thing
My understanding of RPC based on James White’s original definition in RFC 707, is that it is a way of presenting a remote invocation as if it were a local invocation. The details of how its called and therefore the contents of the URL are irrelevant. What is relevant is that a local call, in most languages, has the distinct characteristic of have exactly two outcomes. You either get back the type you were expecting, or you get some kind of exception defined by your programing language of choice. This is the limitation of RPC that makes it a poor choice for building reliable distributed systems. If only Steve Vinoski’s talk, RPC and its Offspring: Convenient, Yet Fundamentally Flawed were still available. He does a much better job than I of explaining the issues.
REST requires flexibility in response handling
The REST uniform interface guarantees that when you make a request to resource, you get a self-descriptive representation that describes the outcome of the request. This could be one of many different outcomes but uses standardized metadata to convey the meaning of the response. It is the highly descriptive nature of the response that allows systems to be built that are resilient of failure and resilient to change. That’s what makes something RESTful.
The URL is a name, nothing more
There is no reason that,
POST /SendUserMessage
could not be a completely RESTful interaction. POST is defined in RFC 7231 as being something that can send data to a processing resource. From the opposite perspective, there is no reason why,
POST /users/501/messages
could not be wrapped in a client library that exposes the method:
Message CreateMessage(int userId)
which is a RPC method.
Names are important to humans
We are in the unfortunate situation that the term REST has been brutally misused by our industry. It makes learning what REST is, really difficult. However, to a large extent, Phil did a really good job of positioning the various distributed architectural approaches. But I don’t believe the distinction he is making between RPC and REST is correct. Hence, my post.