I l @ ve RuBoard |
XML-RPC, as defined on its official web site, is ". . . a spec and a set of implementations that allow software running on disparate operating systems, running in different environments to make procedure calls over the Internet . . ." [1] It was created in 1998 to provide a simple portable framework for transmitting procedure calls and receiving responses over the Internet.
As the preceding definition states, XML-RPC actually consists of two parts : the XML-RPC specification itself, which defines the structure and format of XML-RPC procedure calls and responses; and a set of implementations for different platforms. Because XML-RPC was designed from the get-go to be easily portable, it won't surprise you to hear that it has spawned a diverse array of implementations. As of this writing, the official web site lists more than 50 different implementations in languages such as Lisp, AppleScript, JavaScript, C, Perl, Python, and PHP.
An XML-RPC procedure call is encoded as a well- formed XML document, with both procedure name and arguments enclosed within a <methodCall> document element. This procedure call is transmitted to the XML-RPC server as a standard HTTP POST request. Listing 6.1 demonstrates an XML-RPC request to the server some.quote.server ; the request itself is equivalent to calling the function getRandomQuote("Shakespeare") . Listing 6.1 An XML-RPC RequestPOST /RPC2 HTTP/1.0 User-Agent: Mozilla/4.0 (compatible; MSIE 5.0; Windows 95) Host: some.quote.server Content-Type: text/xml Content-Length: 287 <?xml version="1.0" ?> <methodCall> <methodName>getRandomQuote</methodName> <params> <param> <value> <string>Shakespeare</string> </value> </param> </params> </methodCall> As you can see, the XML-RPC request body is clearly demarcated into two sections.The <methodName> element contains the name of the procedure to be invoked on the remote server, whereas the <params> element encloses a list of arguments to be passed to the remote procedure. Individual arguments are represented by individual <param> elements, which in turn enclose a data-typed value (take a look at the following sidebar entitled "Atypically Yours" for a list of the various data types supported by XML-RPC). The server decodes and interprets the request, processes it, and returns the result to the requesting client, again as an XML-encoded HTTP POST response. Listing 6.2 demonstrates what it might look like. Listing 6.2 An XML-RPC Response to a Successful RPC RequestHTTP/1.0 200 OK Server: QuoteServer/RPC Connection: close Content-Type: text/xml Content-Length: 270 <?xml version="1.0"?> <methodResponse> <params> <param> <value> <string>Good night, sweet prince, and flights of angels sing thee to thy rest.</string> </value> </param> </params> </methodResponse>
Every XML-RPC response must return an HTTP status code of 200 OK ; however, the content of the response differs , depending on whether or not an error occurred while processing the XML-RPC request. The response to a successful RPC invocation looks like Listing 6.2: a document element named <methodResponse> that contains one <params> element enclosing the value returned by the procedure. An unsuccessful RPC invocation generates an error, which looks like Listing 6.3. Listing 6.3 An XML-RPC Response to an Unsuccessful RPC RequestHTTP/1.0 200 OK Server: QuoteServer/RPC Connection: close Content-Type: text/xml Content-Length: 585 <?xml version="1.0"?> <methodResponse> <fault> <value> <struct> <member> <name>faultCode</name> <value> <int>2</int> </value> </member> <member> <name>faultString</name> <value> <string>No quotes by that author</string> </value> </member> </struct> </value> </fault> </methodResponse> In this case, though the document element remains the same, the <params> element is replaced by a <fault> element, which is itself a <struct> containing an error code and a human-friendly error string. That pretty much covers the basics of XML-RPC. For more information and examples, you should refer to the official web site at http://www.xmlrpc.org/, which contains the complete XML-RPC specification (with examples and code samples), a list of implementations for different platforms, tutorials, FAQs, and a discussion forum. |
I l @ ve RuBoard |