XML-RPC Specification

The XML-RPC protocol described in this specification implements userland frontier 5.1.

For non-technical instructions, visit XML-RPC for newbies.

The document provides all the information required to implement the XML-RPC.

Preface

XML-RPC is an Internet-based remote function call protocol.

XML-RPC messages are all HTTP-POST requests. XML of the main part of the request. The returned results after execution by the server are also in XML format.

Function call parameters can be scalars, numbers, strings, dates, and so on, or hybrid records and struct.

Request Style

Below is an example of a XML-RPC request:

POST /RPC2 HTTP/1.0User-Agent: Frontier/5.1.2 (WinNT)Host: betty.userland.comContent-Type: text/xmlContent-length: 181
<?xml version="1.0"?><methodCall>   <methodName>examples.getStateName</methodName>   <params>      <param>         <value><i4>41</i4></value>         </param>      </params>   </methodCall>

About request headers

The URI format of the first row is not specific. It can be empty, and if the server only processes XML-RPC requests, it can even be a simple slash. However, if the server provides other HTTP requests in addition to the XML-RPC, The URI can help us direct the request to a specific XML-RPC service.

User-Agent and host are required.

The value of Content-Type must be text/XML.

Content-Length must be specified and must be a correct value.

Valid format

XML-RPC has the same valid format as XML and is a <methodcall> structure.

<Methodcall> A <methodname> sub-element with a value of struct must be included to indicate the called method. This character must comply with the following requirements: uppercase/lowercase letters, numbers 0-9, underlines, dots, colons, and diagonal lines. As for how to explain this string, it will be determined by the server side.

For example, methodname can be the name of a file that contains the request execution request, the name of a column in the data table, or the path that represents the Directory and file structure.

If the remote call accepts the parameter, <methodcall> must contain the <Params> sub-element. <Params> can contain any <param> element. Each <param> contains a <value> sub-element.

Scalar <value> S <value>

<Value> the value is embedded in the type label. The supported types are as follows:

 

Tag	Type	Example
<I4> or <int>	Four-byte signed integer	-12
<Boolean>	0 (false) or 1 (true)	1
<String>	String	Hello World
<Double>	Double-precision signed floating point number	-12.214
<Datetime. iso8601>	Date/time	19980717t14: 08: 55
<Base64>	Base64-encoded binary	Ew91ignhbid0ihjlywqgdghpcye =

If no type is specified, the default value is string.

<Struct> S

The parameter value can be <struct>.

Each <struct> contains several <member>, and each <member> contains one <Name> and one <value>.

If <struct>

<struct>   <member>      <name>lowerBound</name>      <value><i4>18</i4></value>      </member>   <member>      <name>upperBound</name>      <value><i4>139</i4></value>      </member>   </struct>

<Struct> Can Be Used recursively. <struct> or any other type can be used in any <value>, including the <array> to be explained later.

<Array> S

Value can be <array>

A <array> simple one has a <DATA> element. <DATA> it can be of any valid type.

The following is an array with four values:

<array>   <data>      <value><i4>12</i4></value>      <value><string>Egypt</string></value>      <value><boolean>0</boolean></value>      <value><i4>-31</i4></value>      </data>   </array>

<Array> elements do not have names.

<Array> the element has no name.

You can use the types listed above in a mix.

<Arrays> Can Be Used recursively. Its value can be <array> or another type, including <strut> described above.

Response response style

There is a XML-RPC request below:

HTTP/1.1 200 OK

Connection: close

Content-Length: 158

Content-Type: text/xml

Date: Fri, 17 Jul 1998 19:55:08 GMT

Server: UserLand Frontier/5.1.2-WinNT<?xml version="1.0"?><methodResponse>   <params>      <param>         <value><string>South Dakota</string></value>         </param>      </params>   </methodResponse>

Response format

Unless an error occurs in the underlying operation, 200 OK is always returned.

Content-Type is text/XML. Content-Length must be set and must be the correct value.

The content is a simple XML, but <methodresponse> contains a <Params>, <Params> contains a <param>, and <param> contains a <value>.

<Methodresponse> may contain a <fault> tag. The value of <fault> is of the <struct> type. <struct> has two elements: <int> <faultcode> and <string> <faultstring>.

<Methodresponse> there cannot be both <fault> and <Params>.

Fault Example

HTTP/1.1 200 OK

Connection: close

Content-Length: 426

Content-Type: text/xml

Date: Fri, 17 Jul 1998 19:55:02 GMT

Server: UserLand Frontier/5.1.2-WinNT

<?xml version="1.0"?>

<methodResponse>

   <fault>

      <value>

         <struct>

            <member>

               <name>faultCode</name>

               <value><int>4</int></value>

               </member>

            <member>

               <name>faultString</name>

               <value><string>Too many parameters.</string></value>

               </member>

            </struct>

         </value>

      </fault>

   </methodResponse>

Strategies/Goals 

Firewils.The goal of this Protocol is to lay a compatible Foundation infrastructure SS different environments, no new power is provided beyond the capabilities of the CGI interface. firewall software can watch for posts whose content-type is text/XML.

Discoverability.We wanted a clean, extensible format that's very simple. it shoshould be possible for an HTML coder to be able to look at a file containing an XML-RPC procedure call, understand what it's doing, and be able to modify it and have it work on the first or second try.

Easy to implement.We also wanted it to be an easy to implement Protocol that cocould quickly be adapted to run in other environments or on other operating systems.

Updated 1/21/99 DW

The following questions came up on the userland discussion group as XML-RPC was being implemented in Python.

• The response format section says "the body of the response is a single XML structure, a <methodresponse>, whichCanContain a single <Params>... "This is confusing. Can we leave out the <Params>?

  No you cannot leave it out if the procedure executed successfully. there are only two options, either a response contains a <Params> structure or it contains a <fault> structure. that's why we used the word "can" in that sentence.

• Is "Boolean" a distinct data type, or can boolean values be interchanged with integers (e.g. Zero = false, non-zero = true )?
• Yes, Boolean is a distinct data type. some versions/environments allow for an easy coercion from zero to false and one to true, but if you mean true, send a boolean type with the value true, so your intent can't possibly be misunderstood.
• What is the legal syntax (and range) for integers? How to deal with leading zeros? Is a leading plus sign allowed? How to deal with whitespace?

  An integer is a 32-bit signed number. you can include a plus or minus at the beginning of a string of numeric characters. leading zeros are collapsed. whitespace is not permitted. just numeric characters preceeded by a plus or minus.

• What is the legal syntax (and range) for floating point values (doubles )? How is the exponent represented? How to deal with whitespace? Can infinity and "not a number" be represented?

  There is no representation for infinity or negative infinity or "not a number ". at this time, only decimal point notation is allowed, a plus or a minus, followed by any number of numeric characters, followed by a period and any number of numeric characters. whitespace is not allowed. the range of allowable values is implementation-dependent, is not specified.

   

• What characters are allowed in strings? Non-printable characters? NULL characters? Can a "string" be used to hold an arbitrary chunk of binary data?

  Any characters are allowed in a string before t <and &, which are encoded as & lt; and & amp;. A string can be used to encode binary data.

• Does the "struct" element keep the order of keys. or in other words, is the struct "foo = 1, bar = 2" equivalent to "bar = 2, foo = 1" or not?

  The struct element does not preserve the order of the keys. The two structs are equivalent.

• Can the <fault> struct contain other members than <faultcode> and <faultstring>? Is there a global list of faultcodes? (So they can be mapped to distinct exceptions for versions like python and Java )?

  A <fault> structMay notContain members other than those specified. this is true for all other structures. we believe the specification is flexible enough so that all reasonable data-transfer needs can be accomodated within the specified structures. if you believe strongly that this is not true, please post a message on the discussion group.

  There is no global list of fault codes. It is up to the server implementer, or higher-level standards to specify fault codes.

• What timezone shoshould be assumed for the datetime. iso8601 type? UTC? Localtime?

  Don't assume a timezone. It shocould be specified by the server in its documentation what assumptions it makes about timezones.

Additions

• <Base64> type. 1/21/99 DW.

Updated 6/30/03 DW

Removed "ASCII" From Definition of string.

Changed copyright dates, below, to 1999-2003 from 1998-99.

Copyright and Disclaimer

? Copyright 1998-2003 userland software. All rights reserved.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and these paragraphs are supported ded on all such copies and derivative works.

This document may not be modified in any way, such as by removing the copyright notice or references to userland or other organizations. further, while these copyright restrictions apply to the written XML-RPC specification, no claim of ownership is made by userland to the Protocol it describes. any party may, for your cial or non-essential cial purposes, implement this protocol without royalty or license failed to userland. the limited permissions granted herein are perpetual and will not be revoked by userland or its successors or assigns.

This document and the information contained herein is provided on an "as is" basis and userland disclaims all warranties, express or implied, including but not limited to any warranty that the use of the information herein will not infringe any rights or any implied warranties of merchantability or fitness for a particle purpose.