AsynchronousBlog

A brief history, if you will… the last few years has seen a very strong push towards “Web Services” … using XML and HTTP in order to provide application-to-application services. This push has spawned SOAP and XML-RPC, primarily, as ways to do RPC using HTTP as a transport and XML to encode the data. As well, we’ve seen the identification of REST as a description of the architecture of the Web. In the course of the SOAP and general Web Services discussions, a tangible and often contentious “REST vs. RPC” thread emerged.

The WS-* efforts have been well-intentioned, seeking to build upon the basic specs and each other to provide agreement about increasing levels of complexity. Many of them seem to want to solve interesting problems, while many seem like magic pixie dust. But in any case they are complexity. Not necessarily needless complexity, but complexity none the less.

Thus, more recently, there’s been a very strong and understandable backlash against all of this, especially from a set of people looking to provide simple procedural APIs to developers. They don’t need WS-ReliableMessaging, since TCP is reliable enough. They don’t care about WS-Security because HTTPS is there if necessary. WS-Attachments are silly to them, because they already know how to transmit data…

So they reject it all, and use what they know, the tried, true and simple HTTP and XML. But fundamentally, they’re still representing an RPC interface, so it comes out like this:

To create a foo item, call the “createFoo” procedure by doing an HTTP GET of http://api.example.com/services?operation=createFoo&name=My+first+foo&developerId=12345&applicationId=54321 You will get back the XML document “<created />”. Then you can execute the “getFoo” operation with the same name token as the item you created via http://api.example.com/services?operatoin=getFoo&name=My+first+foo&developerId=12345&applicationId=54321

These APIs are nice and simple, and quite welcome; as such, developers eat them up. Everyone everywhere has a simple HTTP client library, and its often part of the basic development platform. There are hundreds of XML APIs that are all different from each other, and thus all work and suit individual developers tastes. It’s not SOAP and it’s not XML-RPC … it uses HTTP and XML … it must be REST. We now have a RESTful API!

Wrong.

REST does not mean “do RPC over HTTP simply”. There are many other factors involved in it’s description and execution. Using hypermedia as the engine of application state is an important one. This means both identifying “hard” resources within the application such as a news article at /articles/12345 and application states such as /articles/createNew.cgi. REST is heavily intertwingled with well-known representation formats like HTML and its forms; it is described well by web browsers that understand what to do when you click on a <input type="submit"...>.

Another important property of REST is the uniform interface — that we only need to agree to a small and uniform set of operations a-priori … we don’t need an IDL, per se, since there isn’t a novel interface to describe. As the client application, I know that you support GET, and I can use it to safely retrieve a representation of the current state. If you, the server, want me to POST something there’ll be a form that describes what I the client need to do – what fields are necessary and where to POST or GET and in what encoding and … – in order to accomplish some operation. Everything necessary for the application to submit that processing request back to the server and have it be understood will be present in said form.

It is important, for instance, that the server is branching its processing based on a token that the server just provided along with the form, rather than an operation name that the client knows to provide to the server to invoke the operation. To a large extent and in terms of what has made the web so successful, it is vitally important that the client not understand the semantics of the form at all.

REST describes all of that, and more. Calling these APIs RESTful is unfair to REST and to these APIs. It makes it hard[er] to discuss REST, since now REST has it’s original sense plus a “simple RPC over HTTP” sense. As well, it makes it harder to comprehend these “RESTful” APIs, as they should be expected to exhibit all of the constraints that REST sets forth, yet they don’t necessarily.

As such, we need an alternate name for these APIs. I believe a fair label is SHARE: Simple HTTP API of RPC and Encoded data.

I think this name captures the most important aspect of these APIs: their simplicity, use of HTTP, use of the RPC paradigm and trafficing in encoded data. (Okay, the “encoded data” part is silly — what is unencoded data, after all? But it does make the acronym work, so c’mon). More importantly, that they exist in order to share functionality with the other applications or systems.

It is my hope that distinguishing between these two concepts – REST and SHARE – helps allow people to develop both. We have a lot of experience creating procedural interfaces and systems, but the web is demonstrably better at scaling, is more generally useful, &c. I hope that we can find ways to build services and interfaces that are as simple as the procedural ones we’ve come to know and love, but as powerful, flexible and as scaleable as the web. But we’re not going to do that without identifying which is which appropriately.