Tuesday, September 17, 2002

XML-RPC battle scars *sigh* Generally, working with XML-RPC can be quite enjoyable in that it is a simple, but very powerful, protocol. However, far too often the informality of the protocol leads to some serious confusion that can be extremely frustrating to muddle through. The actual XML-RPC "specification" is somewhat at the root of the problem. The spec isn't really a spec -- it is an off the cuff rambling of ideas. While certainly brilliant in its simplicity, it leaves an awful lot to assumption as can be witnessed by the interoperability problems between various clients and servers (oh, you mean I have to quote THAT character but not THIS character?). Now we are trying to take our support for XML-RPC to the next level. Namely, we are trying to build a server API that actually provides useful information via the listMethods, methodHelp and methodSignature RPC methods in a fashion that is standard-- i.e. a fashion that programmatic clients can easily parse to aid in the automatic query and development of web services. Unfortunately, there is basically zero documentation or specification information about these methods. A search of Google reveals quite a bit of discussion about these methods, but no definitive documentation or benchmark implementation. listMethods is supposed to return an array [vector] of strings; each string being the name of a method available via XML-RPC. Looking at the various sample implementations, a number send back much more -- several send a short usage string (i.e. "int foo(string user, int bar") and others return a dictionary with the key being the method name and the value being usage. There is no clues given as to what methodHelp() should return. Just documentation for the method? Documentation and usage? Documentation, usage, examples? Should it be HTML or text/plain? The O'Reilly Meerkat Article indicates that methodSignature returns a two-element array containing the return value and parameter(s) of the method named. Yet, the Meerkat XML-RPC Interface Test Suite (select "listMethods" and click "Run Tests") documents methodSignature indicates Returns an array of known signatures (an array of arrays) for the method name passed. So, which is it? The latter makes more sense -- especially in the context of Java where any given method name can usefully have multiple signatures. Maybe the reason why SOAP -- a specification that is bloated and extremely "chatty" (look at the body of a SOAP call compared to the body of the same XML-RPC call) -- continues to gain in popularity is simply because the spec is formal and complete. Once one implements a server or client to the SOAP spec, the nastiness becomes hidden behind an opaque API. With XML-RPC, I find myself constantly having to dive through the opaque API and screw around in the internals. In this case, I guess we will just have to do what we have done in the past with the XML-RPC feature set -- make it up as we go given as much concensus as we can draw from Google searches and hope for the best when it comes to compatibility. 12:15:37 PM  pontificate