My recent post, Explaining REST To Damien Katz, led to some insightful comments from Dave Winer and Tim Bray about what proponents of building RESTful Web services can learn from remote procedure call (RPC) technologies like SOAP and XML-RPC. 

In his post, Dare left something out (and it's important) Dave Winer wrote

Really ought to include it in your thinking, Dare and everyone else. You're missing out on something that works really well. You should at least learn the lessons and add to REST what it needs to catch up with XML-RPC. Seriously.

What's missing in REST, btw, is a standard method of serializing structs, lists and scalar types. The languages we use have a lot more in common than you might think. We're all writing code, again and again, every time we support a new interface that could be written once and then baked into the kernels of our languages, and then our operating systems. Apple actually did this with Mac OS, XML-RPC support is baked in. So did Python. So if you think it's just me saying this, you should take another look.

Dave has a valid point, a lot of the time communication between distributed systems is simply passing around serialized objects and/or collections of objects. In such cases, having a lightweight standard representation for serialized objects which is supported on multiple platforms would be beneficial. Where Dave goes astray is in his assertion that no such technology exists for developers building RESTful Web services. Actually one does, and it is widely deployed on the Web today. JavaScript Object Notation (JSON) which is described in RFC 4627 is a widely deployed and well-defined media type (application/json) for representing serialized structs, lists and scalar values on the Web. 

There are libraries for processing JSON on practically every popular platform from "corporate" platforms like Java and the .NET Framework to Web scripting languages like Python and Ruby. In addition, JSON is attractive because it is natively available in modern Web browsers that support JavaScript which means you can use it to build services that can be consumed by Web browsers, other Web services or desktop applications with a single end point.

Tim Bray cautioned REST proponents against blindly rejecting the features typically associated with RPC systems and SOAP/WS-* in his post REST Questions where he wrote

Has REST Been Fortunate in its Enemies? · I have been among the most vocal of those sneering at WS-*, and I’m comfortable with what I’ve said. But that doesn’t prove that the core WS-* ideas are wrong. Here are some of the handicaps WS-* struggled under:

  • Lousy foundational technologies (XSD and WSDL).

  • A Microsoft/IBM-driven process that was cripplingly product-linked and political.

  • Designers undereducated in the realities of the Web as it is.

  • Unnecessary detours into Architecture Astronautics.

As a result, we should be really careful about drawing lessons from the failure of WS-*. Specifically:

  • Just because the XSD type system is malformed, you can’t conclude that the notion of schema-driven mapping between program data types and representation payloads is harmful.

  • Just because WSDL is a crock, you can’t conclude that exposing a machine-readable contract for a service is a necessarily bad idea.

  • Just because UDDI never took off, you can’t conclude that service registries are dumb.

  • Just because SOAP has a damaging MustUnderstand facility and grew a lot of ancillary specification hair, you can’t conclude that some sort of re-usable payload wrapper is necessarily a dead-end path.

  • Just because the WS-* security specifications are overengineered and based on a shaky canonicalization spec, you can’t conclude that message-level security and signing aren’t sometimes real important.

And so on. I personally tend to think that schema-driven mapping is hopeless, contracts are interesting, registries are a fantasy, and payload wrappers are very promising. But I don’t think that the history of WS-* is a very good argument for any of those positions.

In a lot of situations where applications consume XML, the first thing the application does is convert the XML into an object graph representative of the business logic of the application. The SOAP/WS-* way of doing this was to define an XSD schema for the XML payload and then use some object<->XML mapping layer to convert the XML to objects. The problem with this approach was that there is a fundamental impedance mismatch between XSD types and OO types which led to horrible interoperability problems since no two platforms could agree on how to map the various esoteric type system features of XSD into the structs, lists and scalar types that are the building block of all OO type systems. However these problems go away if you use a data format that was explicitly designed for describing serialized data objects like JSON.

Providing a machine readable description of a service's end points is useful, especially on the Web where multiple services may expose the same interface. For example, when you visit my weblog at http://www.25hoursaday.com/weblog/ using Firefox 2 or higher and Internet Explorer 7 or higher the browser immediately lights up with a feed icon which allows you to subscribe to my Atom feed from your Web browser. This happens because I've provided a machine readable description of my feed end points on my blog. The Atom Publishing Protocol, which is one of the most well-designed RESTful protocols out there, has a notion of service documents which enable client applications to discover the capabilities and locations of the various end points of the service.

If you put together the notion of service documents with using JSON as the payload format for a service endpoint, you're close to getting the touted programmer friendliness of RPC technologies like XML-RPC & SOAP/WSDL while still building a RESTful service which works with the Web instead of against it.

The only problem is how to deal with statically typed languages like C# and Java. These languages need the types of the objects that application will consume from a Web service defined up front. So if we could just figure out how to come up with service documents for JSON services that included the notion of a class definition, we could pretty much have our cake and eat it to with regards to getting the ease of use of an RPC system while building a RESTful service.

If this sounds interesting to you, then you should go over and read Joe Gregorio's original post on RESTful JSON and then join the restful-json mailing list. Joe's proposal is on the right path although I think he is letting his background as an editor of the Atom Publishing Protocol specification skew his thinking with regards to what developers would find most useful from a Json Publishing Protocol (JsonPub).

Now Playing: G-Unit - Beg For Mercy