Introduction

This document specifies how to interpret a url that uses the "xmlrpc" or "xmlrpcs" scheme. The URL scheme is used to specify XML-RPC requests. Responses are outside the scope of this document.

Description

XML-RPC is a 'method for making Remote Procedure Calls (RPC) using HTTP as the transport and XML as the encoding". The "xmlrpc" and "xmlrpcs" URL schemes defines how XML-RPC calls may be defined in a URL. The responses to any request should be interpreted as described in the XML-RPC specification

If the "xmlrpc" scheme is used without specifying a port, then the well-known HTTP port 80 MUST be used.

If the "xmlrpcs" scheme is used without specifying a port, then the well-known HTTP port 443 MUST be used and SSL transport protection MUST be used.

Syntax

The following BNF uses the syntax from the URL BNF in RFC 1738 (section 5) to describe the syntax of the "xmlrpc" scheme.

	xmlrpcurl  := xmlrpcpref "://" login [ "/" path [ ";"
	              procedureName [ "?" arg "," arg ... ] ] ]

	xmlrpcpref := ( "xmlrpc" | "xmlrpcs" )

	procedureName := alphadigit

	arg := ( struct | array | type ":" data )

	array := "array(" arg "," ... arg ")"

	struct := "struct(" name "=" arg "," ... name "=" arg ")"

	name := alphadigit

	struct := "struct(" arg "," ... arg ")"

	type := ( "string" | "int" | "boolean" | "double" | "base64" |
        	  "dateTime.iso8601" )

	data := alpha | digit | safe

The above BNF MUST NOT be used to replace the XML-RPC specification in any way. It simply defines the structure of an "xmlrpc" or "xmlrpcs" URL.

Examples

The following examples all come from well known services. In most cases their sample requests have been used.

Time Request

xmlrpc://time.userland.com/RPC2;currentTime.getCurrentTime

The above URL would generate the following request:

POST /RPC2 HTTP/1.0
Host: time.xmlrpc.com
Content-Type: text/xml
Content-length: 131

<?xml version="1.0"?>
<methodCall>
  <methodName>currentTime.getCurrentTime</methodName>
  <params>
  </params>
  </methodCall>

Query of syndicated feed

xmlrpc://www.syndic8.com/xmlrpc.php;syndic8.FindFeeds?string:mah.everybody.org

A request for this URL would look like:

POST /xmlrpc.php HTTP/1.0
Host: www.syndic8.com
Content-Type: text/xml
Content-length: 131

<?xml version="1.0"?>
<methodCall>
  <methodName>syndic8.FindFeeds</methodName>
  <params>
    <value>
      <string>mah.everybody.org<string>
    </value>
  </params>
  </methodCall>

Weblog Post

xmlrpc://plant.blogger.com/api/RPC2;blogger.newPost?string:C6CE3FFB3174106584CBB250C0B0519BF4E294,
string:744145,string:ewilliams,string:secret,string:Today%20I%20had%20a%20peanut%20butter%20and%20pickle%20sandwich%20for%20lunch.%20
Do%20you%20like%20peanut-butter%20and%20pickle%20sandwiches?%20I%20do.%20They're%20yummy.%20Please%20comment!,boolean:false

A request for this URL would look like:

POST /api/RPC2 HTTP/1.0
Host: plant.blogger.com
Content-Type: text/xml
Content-length: 515

<?xml version="1.0"?>
<methodCall>
  <methodName>blogger.newPost</methodName>
  <params>
     <param><value><string>C6CE3FFB3174106584CBB250C0B0519BF4E294</string></value></param>
     <param><value><string>744145</string></value></param>
     <param><value><string>ewilliams</string></value></param>
     <param><value><string>secret</string></value></param>
     <param><value><string>Today I had a peanut butter and pickle sandwich for lunch. Do you like peanut-butter and pickle sandwiches? I do. They're yummy. Please comment!</string></value></param>
     <param><value><boolean>false</boolean></value></param></params> </methodCall>

Security

SSL may be used for transport protection. The url scheme "xmlrpcs" should be used to indicate this.

HTTP Authentication may be used for authentication.

The effect of using long "xmlrpc" URLs in applications is currently unknown; some software packages may exhibit unreasonable behavior when confronted with URL lengths that exceeds its allocated buffer size.

References

The XML-RPC Specification (http://www.xmlrpc.com/spec)

Using XML-RPC in BEEP (http://www.ietf.org/internet-drafts/draft-harold-beep-xmlrpc-03.txt)

The "data" URL scheme (RFC 2397)