XML-RPC Specification

1<methodcall>
2<methodname>examples.getStateName</methodname>
3<params>
4<param/>
5<value><i4>41</i4></value>
6</params>
7</methodcall>

  1<methodcall> structure. 
  2
  3The <methodcall> must contain a <methodname> sub-item, a string, containing the name of the method to be called. The string may only contain identifier characters, upper and lower-case A-Z, the numeric characters, 0-9, underscore, dot, colon and slash. It's entirely up to the server to decide how to interpret the characters in a methodName. 
  4
  5For example, the methodName could be the name of a file containing a script that executes on an incoming request. It could be the name of a cell in a database table. Or it could be a path to a file contained within a hierarchy of folders and files. 
  6
  7If the procedure call has parameters, the <methodcall> must contain a <params> sub-item. The <params> sub-item can contain any number of <param/>s, each of which has a <value>. 
  8
  9**Scalar <value>s **
 10
 11<value>s can be scalars, type is indicated by nesting the value inside one of the tags listed in this table: 
 12
 13**Tag** |  **Type** |  **Example**  
 14---|---|---  
 15  
 16<i4> or <int> |  four-byte signed integer  |  -12   
 17  
 18<boolean> |  0 (false) or 1 (true)  |  1   
 19  
 20<string> |  string  |  hello world   
 21  
 22<double> |  double-precision signed floating point number  |  -12.214   
 23  
 24<datetime.iso8601> |  date/time  |  19980717T14:08:55   
 25  
 26<base64> |  base64-encoded binary  |  eW91IGNhbid0IHJlYWQgdGhpcyE=   
 27  
 28If no type is indicated, the type is string. 
 29
 30** <struct>s **
 31
 32A value can also be of type <struct>. 
 33
 34A <struct> contains <member>s and each <member> contains a <name> and a <value>. 
 35
 36Here's an example of a two-element <struct>: 
 37    
 38    
 39    <struct>
 40<member>
 41<name>lowerBound</name>
 42<value><i4>18</i4></value>
 43</member>
 44<member>
 45<name>upperBound</name>
 46<value><i4>139</i4></value>
 47</member>
 48</struct>
 49<struct>s can be recursive, any <value> may contain a <struct> or any other type, including an <array>, described below. 
 50
 51** <array>s **
 52
 53A value can also be of type <array>. 
 54
 55An <array> contains a single <data> element, which can contain any number of <value>s. 
 56
 57Here's an example of a four-element array: 
 58    
 59    
 60    <array>
 61<data>
 62<value><i4>12</i4></value>
 63<value><string>Egypt</string></value>
 64<value><boolean>0</boolean></value>
 65<value><i4>-31</i4></value>
 66</data>
 67</array>
 68<array> elements do not have names. 
 69
 70You can mix types as the example above illustrates. 
 71
 72<arrays>s can be recursive, any value may contain an <array> or any other type, including a <struct>, described above. 
 73
 74**Response example**
 75
 76Here's an example of a response to an XML-RPC request: 
 77    
 78    
 79    HTTP/1.1 200 OK
 80    Connection: close
 81    Content-Length: 158
 82    Content-Type: text/xml
 83    Date: Fri, 17 Jul 1998 19:55:08 GMT
 84    Server: UserLand Frontier/5.1.2-WinNT
 85    
 86    
 87    
 88    <?xml version="1.0"?>
 89<methodresponse>
 90<params>
 91<param/>
 92<value><string>South Dakota</string></value>
 93</params>
 94</methodresponse>
 95    
 96
 97**Response format**
 98
 99Unless there's a lower-level error, always return 200 OK. 
100
101The Content-Type is text/xml. Content-Length must be present and correct. 
102
103The body of the response is a single XML structure, a <methodresponse>, which can contain a single <params> which contains a single <param/> which contains a single <value>. 
104
105The <methodresponse> could also contain a <fault> which contains a <value> which is a <struct> containing two elements, one named <faultcode>, an <int> and one named <faultstring>, a <string>. 
106
107A <methodresponse> can not contain both a <fault> and a <params>. 
108
109**Fault example**
110    
111    
112    HTTP/1.1 200 OK
113    Connection: close
114    Content-Length: 426
115    Content-Type: text/xml
116    Date: Fri, 17 Jul 1998 19:55:02 GMT
117    Server: UserLand Frontier/5.1.2-WinNT
118    
119    
120    
121    <?xml version="1.0"?>
122<methodresponse>
123<fault>
124<value>
125<struct>
126<member>
127<name>faultCode</name>
128<value><int>4</int></value>
129</member>
130<member>
131<name>faultString</name>
132<value><string>Too many parameters.</string></value>
133</member>
134</struct>
135</value>
136</fault>
137</methodresponse>
138    
139
140**Strategies/Goals**
141
142_Firewalls._ The goal of this protocol is to lay a compatible foundation across 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. 
143
144_Discoverability._ We wanted a clean, extensible format that's very simple. It should 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. 
145
146_Easy to implement._ We also wanted it to be an easy to implement protocol that could quickly be adapted to run in other environments or on other operating systems. 
147
148**Updated 1/21/99 DW**
149
150The following questions came up on the UserLand discussion group as XML-RPC was being implemented in Python. 
151
152  * The Response Format section says "The body of the response is a single XML structure, a <methodresponse>, which _can_ contain a single <params>..." This is confusing. Can we leave out the <params>? 
153
154No 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. 
155
156  * Is "boolean" a distinct data type, or can boolean values be interchanged with integers (e.g. zero=false, non-zero=true)? 
157
158Yes, boolean is a distinct data type. Some languages/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. 
159
160  * 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? 
161
162An 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. 
163
164  * 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? 
165
166There 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. 
167
168  * What characters are allowed in strings? Non-printable characters? Null characters? Can a "string" be used to hold an arbitrary chunk of binary data? 
169
170Any characters are allowed in a string except &lt; and &amp;, which are encoded as &lt; and &amp;. A string can be used to encode binary data. 
171
172  * 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? 
173
174The struct element does not preserve the order of the keys. The two structs are equivalent. 
175
176  * 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 languages like Python and Java)? 
177
178A <fault> struct **may not** contain 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. 
179
180There is no global list of fault codes. It is up to the server implementer, or higher-level standards to specify fault codes. 
181
182  * What timezone should be assumed for the dateTime.iso8601 type? UTC? localtime? 
183
184Don't assume a timezone. It should be specified by the server in its documentation what assumptions it makes about timezones. 
185
186
187
188
189**Additions**
190
191  * <base64> type. 1/21/99 DW. 
192
193
194
195**Updated 6/30/03 DW**
196
197Removed "ASCII" from definition of string. 
198
199Changed copyright dates, below, to 1999-2003 from 1998-99. 
200
201**Copyright and disclaimer**
202
203© Copyright 1998-2003 UserLand Software. All Rights Reserved. 
204
205This 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 included on all such copies and derivative works. 
206
207This 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 commercial or non-commercial purposes, implement this protocol without royalty or license fee to UserLand. The limited permissions granted herein are perpetual and will not be revoked by UserLand or its successors or assigns. 
208
209This 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 PARTICULAR PURPOSE.</base64></fault></faultstring></faultcode></fault></fault></params></params></params></methodresponse></params></fault></methodresponse></string></faultstring></int></faultcode></struct></value></fault></methodresponse></value></params></methodresponse></struct></array></arrays></array></value></data></array></array></array></array></struct></value></struct></struct></value></name></member></member></struct></struct></struct></base64></datetime.iso8601></double></string></boolean></int></i4></value></value></value></params></params></methodcall></methodname></methodcall></methodcall>