[Docs] [txt|pdf] [Tracker] [Email] [Diff1] [Diff2] [Nits]
Versions: 00 01
Internet-Draft Mario Salzer
draft-salzer-xmlplusrpc-01.txt
Category: Experimental
Expires: January 2005 July 2004
XML+RPC - XML marshalled Remote Procedure Calls
(DRAFT)
Status of this Memo
This document is an Internet-Draft and is subject to all provisions
of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as
Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six
months and may be updated, replaced, or obsoleted by other
documents at any time. It is inappropriate to use Internet-
Drafts as reference material or to cite them other than as
"work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/1id-abstracts.html
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html
This document expires again in January 2005.
Copyright Notice
Copyright (C) The Internet Society 2004. All Rights Reserved.
Abstract
This document describes a method to make use of remotely available
application logic and data processing by sending explicit procedure
calls encoded in simple and plattform-independent XML messages over
a HTTP connection.
Despite other RPC (Remote Procedure Call) implementations it is
not encoded as binary data, and concentrates on the most basic
functionality. Therefore it is easier to implement and compatible
with various programming languages and data representation systems.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . $
1.1 Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . $
1.2 Relationship to "XML-RPC" . . . . . . . . . . . . . . . . . $
1.3 Requirements . . . . . . . . . . . . . . . . . . . . . . . $
1.4 Terminology . . . . . . . . . . . . . . . . . . . . . . . . $
2. Remote Procedure Calls
2.1 Overall Operation
2.2 Example Call
3. Message Body Syntax
3.1 XML Compliance
3.1.1 Restricted XML Syntax
3.1.2 Character Encoding
3.1.3 No DTD
3.2 Request Messages
3.3 Response Massages
3.4 Error Responses
3.5 Simple Data Types
3.5.1 Boolean
3.5.2 Integer
3.5.3 Double
3.5.4 Date And Time
3.5.5 String
3.5.6 Binary Base64
3.6 Aggregate Data Types
3.6.1 Array
3.6.2 Struct
3.7 Custom Data Types
4. Transportation Over HTTP
4.1 General Discussion
4.1.1 MIME Media Type "application/rpc+xml"
4.1.2 Charset parameter
4.2 Requests
4.3 Responses
4.3.1 Transport Layer Errors
4.4 HTTP Transport Compression
4.4.1 Transport Feature Handshake Requests
4.5 Server Requirements
5. Implementation Notes
5.1 Error Response Codes
5.2 Standardized System Methods
5.2.1 system.listMethods
5.2.2 system.methodSignature
5.2.3 system.multiCall
5.2.4 system.dataTypes
5.3 Compatibility with XML-RPC
5.3.1 Older Media Type
5.3.2 Use Of A XML-Parser
5.4 Simplifications
5.4.1 HTTP/1.0 To Avoid Chunked Encoding
6. IESG Section
6.1 IANA Media Type Registration
6.2 Security Considerations
7. Acknowledgements
8. Appendix
9. (draft TODO list)
1. Introduction
1.1 Purpose
Remote Procedure Calls allow to share out programm logic and even
data storage across multiple networked hosts. The concept of these
calls is very similar to that of machine local procedure calls,
which often are encoded in machine code and call procedures based
on the machines memory access model and processor registers.
Unlike local procedure calls and most earlier RPC implementations
XML+RPC does not use binary coding to transform send data, but
instead uses a XML format for cross-plattform compatibility. The
overall design goal was to make it easy to implement and use. It
provides only the most basic data types to be useful in conjunction
with nearly all programming languages and computer plattforms, which
often differ wideley in how data types are internally represented.
1.2 Relationship to "XML-RPC"
The protocol described within this document is almost identical
to of UserLands [MINUS] specification as written by Dave Winer,
but that some clearifications were added. Much care has been
taken to keep all older implementations of that specification
compatible.
"XML-RPC" is a registered trademark of UserLand. (?)
1.3 Requirements
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
An implementation is conforming to this specification if it
implements all requirements of this document expressed with "MUST",
and all forbidden misinterpretations marked with "MUST NOT" were
absent.
This document also makes use of the ABNF schemas as described in
[RFC2234] for clear specification of the XML+RPC message body syntax.
A few paragraphes also utilize regular expressions as introduced by
the Perl programming language to fully define the syntax of other
constructs.
1.4 Terminology
Multiple technical and RFC related terms are used within this
document without prior explanation. However here is a list of terms
specifically used in this document, which are believed to require
definition first.
method
A remotely callable procedure.
gateway
An installation of the XML+RPC interface, which provides methods,
procedures and funtionality for remote access.
procedure
A function that is callable by using the XML+RPC interface
installed on or as webserver.
server
Means the actual implementation of the XML+RPC interface, which
often however is not a server daemon on its own, but implemented
as CGI script and running below an existing server.
tag
A "tag" is a XML token enclosed in angle brackets. Often this is
also code a "node".
vendor
One of the various organisations, companys and individuals that
provide an implementation of XML+RPC. For example Apache.org or
UserLand.
whitespace
Is the class of invisible characters, which includes the space
(%x20) and tabulator (%x08) as well as carriage return (%x0D) and
the new line character (%x0A).
2. Remote Procedure Calls
2.1 Overall Operation
A Remote Procedure Call takes place between two machines. One of
them usually provides functionality the other likes to access. We
further speak of the server for the machine providing methods and the
client that sends processing requests to it.
A RPC is initiated by a client if its programm logic dictates or
requires to invoke a procedure on a remote machine. It then
X constructs a request from the available data, often by using a
X specialised XML+RPC library. The required data is made up of the
full canonical name of the remote procedure and all the parameter
data it requires. The parameter data thereby must first be converted
from the machine representation into XML document text strings.
The request is then packaged into a HTTP request, which is send to
a remote server to process it. If the server accepts XML+RPC
requests at the specified address (URL) it decodes it the XML
document text stream into a structure useful on the server machine
and within the implemented programming language. Then it of
course tries to match the requested method name against a list of
available ones and additionally checks parameter types against the
expected ones so strong typed languages wouldn't be breaked.
If the called procedure finishes the server encodes the request or
an error message again into XML+RPC and sends this back to the
client. The client then decodes the message again and transforms
the result data back into its machine representation and continues
to use that data within the stopped programm logic.
Of course Remote Procedure Calls could also be implemented
asynchronous, but it is often more convinient that the client stops
programm execution while the contacted server works on the XML+RPC
request.
2.2 Example Call
As already explained XML+RPC works by encoding requests into XML
and transferring them over HTTP. This short example tries to
show how a such a call often works.
We assume that the client is running a programm written in the C
programming language and wishes to execute remote procedure code
on another machine while it processes following code:
char *var;
var = xmlrpc("http://example.com/rpc.cgi",
"server.sprintf", "%s - %i", "Hello World!", 2);
The examplary XML+RPC library expressed as xmlrpc() call here could
then encode the call to the remote procedure "server.sprintf" with
exactly three parameters as follows:
POST /rpc.cgi HTTP/1.0
Host: example.com
Accept: application/rpc+xml, text/xml
Accept-Encoding: gzip, deflate
Content-Type: application/rpc+xml
Content-Length: xxxx
<?xml version="1.0"?>
<methodCall>
<methodName>server.sprintf</methodName>
<params>
<param>
<value><string>%s - %i</string></value>
</param>
<param>
<value><string>Hello World!</string></value>
</param>
<param>
<value><int>2</int></value>
</param>
</params>
<methodCall>
Server side this call would likeley be accepted as it conforms to
the XML+RPC syntax, and the destination function "system.printf"
would be executed in a scripting language. After letting the
procedure return a result, the XML+RPC server would then likely
construct an answer like this:
HTTP/1.0 200 OkiDoki
Server: Apache/2.0.86 OpenSSL/0.99.9.9j-9
Accept: application/rpc+xml
Accept-Encoding: deflate, gzip
Content-Type: application/rpc+xml
Content-Length: xxxx
<?xml version="1.0"?>
<methodResponse>
<params>
<param>
<value><string>Hello World! - 2</string></value>
</param>
</params>
</methodResponse>
The client side XML+RPC library would place that return value into
where it was requested.
3. Message Body Syntax
3.1 XML compliance
A compliant implementation MUST obey the [XML] specification when
constructing and parsing procedure calls marshalled as described
by this document.
Because there exist various implementations that don't use a fully
bloated and standards compliant XML parser and there are certain
(security) restrictions for XML+RPC message processing on the
server side, this specification makes a few more recommendations
on which XML features to avoid, if possible.
3.1.1 Restricted XML Syntax
Namespaces are not allowed, and no XML element attributes should be
used as neither the [MINUS] description or this document allow them
for any of the data type tags. Implementations should reject all
messages that contain unknown or unsupported tags or attributes,
which after all could completely distort a requests data.
CDATA sections should be used with care (only in <string> tags) and
only XML Entities & and < are required to be encoded, but ">"
and """ and "'" have to be decoded as well.
3.1.2 Character Encoding
When following the [MINUS] description the default charset= of HTTP
transfered XML-RPC calls has been Latin-1. This specification however
advises to use a MIME Type from the IETF "application" tree, in which
case no default charset shall be assumed. Thus only the encoding=
parameter of the initial <?xml?> processing instruction has to be
evaluated.
The default charset for [XML] then is UTF-8, and implementors are
recommended to use that preferrably and always include the encoding=
parameter in the initial XML processing instruction, even if the [XML]
standard allows plain ASCII, ISO-8859-1 and all flavours of UTF-16 as
well.
3.1.3 ??? (or move below)
Implementors may be tempted to define XML entities like &false; or &true;
for use in <boolean> data type tags, but as XML+RPC was created to be
processed by applications only, this is considered unnecessary bloat syntax
and again a slowdown and should therefore be avoided in general.
3.1.4 No DTD
XML+RPC messages SHOULD NOT contain or reference a DTD, especially
not reference one that was located remotely.
(<s>link</s> to the warning article about remotely located DTDs,
mangling of XML document meaning caused by entity overrides...)
3.2 Request Messages
A XML+RPC request message is supposed to invoke a remote procedure,
and therefore names the remote method to be activated with all the
parameters it expects. The structure of a request message is always
as follows:
XML-processing-instr = '<?xml version="1.0" encoding="UTF-8"?>'
Request-Message = XML-processing-instr
"<methodCall>"
method-name
parameters
"</methodCall>"
method-name = "<methodName>" name "</methodName>"
parameters = "<params>" *(single-parameter) "</params>"
single-parameter = "<param>" (value) "</param>"
Hereby only the <methodName> tag is not permitted to carry any count
of whitespace. (value) is defined later in the Data Types paragraph.
3.3 Response Massages
Unless a XML+RPC call resulted in an error, a server response MUST
have following format:
Response-Message = XML-processing-instruction
"<methodResponse>"
parameters
"</methodResponse>"
XX The <params> sub node MUST always be present. It always contains
XX exactly one <param> node.
3.4 Error Responses
In case of an error a server will sent a message that differes from
the above specified format:
Error-Response = XML-processing-instruction
"<methodResponse>"
fault
"</methodResponse>"
fault = "<fault>"
failure-struct
"</fault>"
Where the failure-struct is a <value> node containing a <struct> node
as described later. The struct then contains two elements, the first
being named "faultCode" and associtated with an integer, and the
second is a string and associated by "faultString".
The string thereby corresponds to the returned error number, but both
are application dependant, except for the error response numbers
described in the section 5.?.? of this document.
3.5 Simple Data Types
Data and values encoded in XML+RPC messages are always of a certain
type. The plattform and programming language used by the server and
the client, and therefore all system depended types must first be
converted into a string expression suitable for almost human-readable
form for transportation inside the XML stream. Data types are always
mapped to a XML+RPC type and encoded into and from a string
representation.
Only a few data types are defined by this document, in order to
provide high interoperability between systems and programming
languages, that often could handle a far larger amount and much more
complex data types. Therefore programmers must take care to convert
the used data structures in the basic types defined by XML+RPC.
Every value is encoded as string (from its processor- or language-
dependant representation) and written as string into a data type tag
additionally enclosed in a <value> tag:
value = "<value>"
data-type-tag
"<value>"
data-type-tag = (data-type-string | data-type-integer
| data-type-boolean | data-type-double
| data-type-base64 | data-type-datetime
| data-type-array | data-type-struct )
The "<value>" tag
3.5.1 Boolean
Boolean values are in many programming languages just represented
by a value of 0 mapped to false and some integer different from 0
as being true. But in order to interoperate reliably and to provide
type checking on either side of the participating implementations,
XML+RPC uses an explicit boolean type.
data-type-boolean = "<boolean>"
(0 | 1)
"</boolean>"
Where 0 corresponds to false and 1 represents the true value. There
is no whitespace permitted between the opening and closing tag.
3.5.2 Integer
Integer values in XML+RPC can contain 32 bit signed values, that is
values in the range from (1 - 2^31) to (0 + 2^31) or more precisely
from -2147483647 to 2147483648. The string of decimal numbers that
make up the string representation of a machines integer value
representation may be preceeded by a minus character, but also can
have a plus sign in front.
integer-value = 0*1 ("+" | "-") integer-string
data-type-integer = "<int>" integer-value "</int>"
| "<i4>" integer-value "</i4>"
Here the data-type tag can be "<int>", but "<i4>" is allowed for
backwards compatiblity with [MINUS].
Whitespace is again not permitted between the opening and the closing
data type tags.
3.5.3 Double
Floating point values can be transmitted using the "<double>" data
type tag. The sender must first encode the value from its machine
representation into a string only consisting of at least one digit
before and at least one digit after a full stop charachter (%x25).
A minus or plus sign may however preceed the string representation
of the floating point value.
double-string-representation =~ /^[+-]?\d+[.]\d+$/
data-type-double = "<double>"
double-string-representation
"</double>"
XX Size restrictions for compatibility??
Whitespace is again not permitted to occour within this data type
tag.
3.5.4 Date And Time
Combined data and time values can be transported over XML+RPC using
the "<dateTime.iso8601>" date type, with the time value encoded
according to [ISO8601]. Basically it is a 14 octets string built
out of the 4 year number digits followed by two digits for the month
and two for the day, then a literal "T" character and the hour,
minutes and seconds with two digits each but separated by colons.
iso8601-time-string =~ /^(\d{4})(\d\d)(\d\d)T(\d\d):(\d\d):(\d\d)$/
data-type-datetime = "<dateTime.iso8601>"
iso8601-time-string
"</dateTime.iso8601>"
The text node of the <dateTime.iso8601> tag may again not contain any
whitespace. Differently to the original [MINUS] specification, the
date and time values of XML+RPC always MUST be specified according to
the [UTC].
3.5.5 String
A string can be encoded in a XML+RPC message by enclosing it in the
"<string>" tag. As outlined in section 3.1.2 a string may contain
any combination of octets, but should be preferrably in the UTF-8
encoding. Also a string MAY contain binary data, and is not limited
in length. Only the XML entities "<", ">" and "&" are to
be decoded when receiving a "<string>" data value.
Unlike all previous data type tags, the string tags text node MAY
contain whitespace, which then however MUST NOT be ignored by the
recipant, but instead then belongs to the enclosed character string
data stream.
string-data-type = "<string>"
string-stream
"</string>"
The older XML-RPC specification also allowed to leave out the
"<string>" data type tag and to write the string text node directly
into the "<value>" tag. Messages encoded according to this document
MUST NOT use this syntax, and never enclose a string value without a
corresponding <string> type tag around. However for compatibility
reasons implementors MAY choose to accept such uncleanly packaged
values.
There is no size restriction for <string> content, and this data type
SHOULD generally preferred over <base64> unless you are intentionally
transporting real binary content.
3.5.6 Binary Base64
XX The <base64> data type was introduced in XML-RPC before the whole
XX stream was later defined to be binary-safe. Therefore the <base64>
XX data type, originally introduced for carrying binary data within
the messages as almost outdated today and of little value for XML+RPC
transportation over HTTP. However if a transport other than HTTP is
to be used, then the <base64> data type MAY be preferred over the
<string> type.
base64-data-type = "<base64>"
base64-string-stream
"</base64>"
The base64-string-stream is a string encoded with the base64 method,
and thus only contains characters in the range from %x30-%x39 and
%x41-%x5A and %x61-%x7A but also %x3D and OPTIONAL whitespace
characters.
3.6 Aggregate Data Types
Besides the most basic data types most programming languages also
provide more complex compound variable types. XML+RPC does however
not allow each possible type to be used, but instead concentrates on
the minimum of interoperable set of types. The two most important
complex data types choosen to be provided by XML+RPC and XML-RPC are
the array and the struct constructs.
Like the basic types, the more complex constructs like array and
struct are always enclosed in a <value> tag, but itself contain more
than one subnode.
3.6.1 Array
An array is an ordered list of data values, with each of them having
the same data type then again. Arrays are provided by most
programming languages, even if they sometimes are called very
differently.
data-type-array = "<array>"
"<data>"
*(value)
"</data>"
"</array>"
Please note that the "<array>" tag itself always has the redundant
"<data>" sub node, which always MUST be present, regardless if there
are any values in the array. The number of values is not limited,
and an implicit numbering is assumed.
The values of an array may itself be any simple or aggregate data
type, but all MUST be of the same type for compatibility reasons
with strong typed programming languages.
3.6.2 Struct
The <struct> data type corresponds to the "struct" in C and to the
"hash arrays" in most interpreted and scripting languages. A struct
has multiple entries, each assigned a name and a value. The order
of the struct members is insignificant, and at least one member MUST
be present.
data-type-struct = "<struct>"
1*(struct-member)
"</struct>"
struct-member = "<member>"
"<name>" token "</name>"
(value)
"</member>"
The "<name>" subnode MUST preceed the also always present "<value>"
sub node in each "<member>" tag. The struct member name assigned
withing the "<name>" tag again MUST NOT contain any whitespace, and
should be moreover only constructed of letters, numbers and the
underscore to meet naming requirements of most programming languages.
3.7 Custom Data Types
Multiple incompliant [MINUS] implementations already arised, because
of the wish to transfer data of programming language specific types
that aren't generic enough to be supported by an inter-plattform
compatible specification like this. Implementors are strictly advised
not to introduce incompatibilites by inventing new data type tags. If
at all necessary, the following workaround SHOULD be used to represent
more complex and system specific data types.
user-data-type = "<struct>"
"<member>"
"<name>type</name>"
"<value>" (string-data-type) "</value>"
"</member>"
"<member>"
"<name>value</name>"
(value)
"</member>"
"</struct>"
A struct with exactly two elements ("type" and "value") should be used
as placeholder for any non-standard data type. The "value" member can
itself be of any other data type, whatever would be most appropriate
for it. Using this scheme the XML+RPC message doesn't get invalid if
custom types get introduced. It can however easily be deciphered into
language and system specific representations if the reciever knows
about the negotiated "type" identifier string and how to unpack the
"value" member into its system representation.
4. Transportation Over HTTP
4.1 General Discussion
This document only specifies and discusses, how XML+RPC messages are
to be transmitted over HTTP. Still it is possible to use different
transport channel, but this is out of the scope of this file.
When a client makes a RPC to a server, it encodes the method name and
call parameters into a message as described in the previous sections,
and transfers that message to the server using a POST method request
as defined by the HTTP specification [RFC2616]. It must correctly
set multiple HTTP request headers and also the response send by the
server, which needs to obey to likewise strict rules.
The meta data required for compliant transmission over HTTP is
discussed in the following paragraphs.
4.1.1 MIME Media Type "application/rpc+xml"
All messages conforming to this specification SHOULD be sent using
a MIME type of "application/rpc+xml". For compatibility with older
[MINUS] compliant servers, an implementation MAY however obey this
rule and use "text/xml" instead for compatibility reasons. This type
is to be specified within the "Content-Type" header field for both,
requests and responses.
This media type is to be registered with the IANA later in this
document. The choosen semantics specifically conforms to [RFC3023]
and indicates compliant software that the content is a XML derrived
format.
4.1.2 Charset Parameter
A MIME type charset= parameter should only be specified when using
"text/xml" in compatibility mode. For "application/rpc+xml" no
implicit charset exists and the XML processing instruction soley
defines the used character encoding.
4.2 Requests
A request MUST be submitted using the POST request method. The
destination URL to pass the request to is not specified by this
document and is installation dependend, while of course servers could
releay messages merely based on the previously defined very specific
media type as well.
In accordance to [RFC2616] a POST request must not only have a MIME
Content-Type header field, but also a Content-Length field, which
specifies the length of data transferred in the body of the request.
A typical request could therefore look like (each line separated by
%x0D%x0A and the body example shortened):
POST /cgi-bin/plus.cgi HTTP/1.0
User-Agent: plus-client/2.5.2
Accept: application/rpc+xml, text/xml; q=0.01
Accept-Encoding: deflate, gzip
Content-Type: application/rpc+xml
Content-Length: 4321
<?xml version="1.0" encoding="UTF-8"?>
<metho...
A client may include all header fields as defined in [RFC2616] and
MUST always indicate the correct media type. And moreover a client is
advised to provide a useful Accept: and Accept-Encoding: field for
negotiation with the server.
The initial request may also be compressed, but many implementations
do not process that correctly and simply fail. HTTP compliant Web
server would answer at least with an error 415 response.
4.3 Responses
Likewise a server response MUST obey all rules of the transport
protocol, and include a correct MIME media type describing the body
message. For compatiblity with [MINUS] compliant clients a server
MAY send a Content-Type: header of "text/xml" if the clients initial
request was of that type and its Accept: header didn't indicate that
it supported XML+RPC fully. A typical response would look like:
HTTP/1.1 200 OK
Date: Mon, 19 Jan 2004 17:17:17 GMT
Accept: application/rpc+xml, text/xml
Accept-Encoding: gzip, deflate
Connection: close
Server: Apache/2.0.94 OpenSSL/0.9.9.9i-9
X-Server: plus-server/2.5.2
Content-Type: application/rpc+xml
Content-Encoding: gzip
Content-Length: 1234
_?H@h1K@@CstxD$&rQx
...
In this example the body data was compressed according to the
acceptable compression methods specified by the previous examples`
client. Implementors are advised to add support for content-coding
according to [RFC2616] to reduce bandwidth use for data intensive
remote procedure calls.
5. Implementation Notes
5.3 Error Response Codes
The <struct> returned with a <fault> response always gives an error
number together with a human readable error description. Since
negotiation [FAULTC] on the most often used error codes, the range
from -32768 till -32000 is reserved for generic error codes and should
not be used for application error codes.
The currently registered and known error results are as follows:
+--------+-------------------------------------------------------+
| Number | Error string |
+--------+-------------------------------------------------------+
| -32300 | Transport error |
+--------+-------------------------------------------------------+
| -32400 | System error |
+--------+-------------------------------------------------------+
| -32500 | Application error |
+--------+-------------------------------------------------------+
| -32600 | (Server) - invalid message format |
+--------+-------------------------------------------------------+
| -32601 | (Server) - requested method does not exists |
+--------+-------------------------------------------------------+
| -32602 | (Server) - invalid method parameters |
+--------+-------------------------------------------------------+
| -32603 | (Server) - internal XML-RPC error |
+--------+-------------------------------------------------------+
XX | -32604 | Too many parameters |
+--------+-------------------------------------------------------+
XX | -32605 | Parameter type mismatch |
+--------+-------------------------------------------------------+
| -32700 | (Parsing) - Not well-formed XML |
+--------+-------------------------------------------------------+
| -32701 | (Parsing) - Unsupported encoding - XML parsers only |
| | must support UTF-8, ISO-8859-1, ASCII and UTF-16 |
+--------+-------------------------------------------------------+
| -32702 | (Parsing) - invalid characters, encoding mismatch |
+--------+-------------------------------------------------------+
XX still wrong here, TODO: incorporate the almost-agreed-on numbers
XX some pretty silly entries here? a few of those errors are transport
XX (HTTP) errors - a 415 HTTP error would do for malformed XML
All other error codes are free to be used to signalise internal
method processing errors, while -32500 could be used as generic
return code in such cases (not recommended). The human readable
error string should contain as much information as possible (up to an
method call syntax description).
5.4 Standardized System Methods
The wideley implemented system.*() call package provides interesting
stuff... TODO
5.4.1 system.listMethods()
Returns an array of strings, each the name of a callable remote
procedure... TODO
5.4.2 system.methodSignature()
Allows to query parameter and return variables number and types
for a given method name... TODO
5.4.3 system.multiCall()
Packages multiple calls in an array with specifically designed
structs, where each mimics a single XML+RPC method call. The result
is an array likewise... TODO
5.4.4 system.dataTypes()
This call is a recommendation to allow for future extensibility. The
described procedure call will return an array of strings, which name
data types supported by the queried server... TODO
Would return an array with [ "boolean", "int", "double", "string",
"dateTime.iso8601", "base64", "array", "struct" ] for unextented
implementations of this specification. Note the absence of the "i4"
type, which is deprecated by now.
An implementation could invent new types (like "nil" or "unicode"
or even "object") and signalise support by means of this method call.
See paragraph 3.7 of this document on how to encode extended data
types without breaking intercompatibility.
Note, that this information however can only by queried from the
server by a client, so that a server could never assume the client to
support an extended data type unless there is a way to negotiate on
this.
5.3 Compatibility with XML-RPC
Maintining backwards compatibility with XML-RPC may not be desired,
but is a simple task, because there were basically no changes to
XML+RPC, except for some deprecations and minor transport level
enhancements.
5.3.1 Older Media Type
The MIME media type "text/xml" was falsely used by [MINUS] compliant
servers and clients and is likely to quickly disappear with final
registration of the more appropriate "application/rpc+xml" MIME type.
Implementations compliant to the rules outlined in this document may
however provide and signalise compatibility to unfixed clients and
servers by means of handshake requests and Accept: type negotiation.
5.3.2 Use Of A XML-Parser
5.4 Simplification Recommendations -cut-
6. IESG Section
6.1 IANA Media Type Registration
To: ietf-types@iana.org
Subject: Registration of Standard MIME Media type application/rpc+xml
MIME media type name: application
MIME subtype name: rpc+xml
Required parameters: none
Optional parameters: none
Encoding considerations:
The message format can contain arbitrary binary data, and thus
MUST be encoded for non-binary transport channels such as SMTP.
The base64 encoding is suitable for transport protocols other
than HTTP.
Security considerations:
See section 7.2 of this document.
Interoperability considerations:
Registration of this Media Type happens to correct the abuse of
the "text/xml" MIME Type within XML-RPC transmissions following
the [MINUS] spec.
Published specification:
Use of the Media Type is described within this document.
Applications which use this media type:
...
Additional information:
Magic number(s): none
File extension(s): none
Macintosh File Type Code(s): none
Object Identifier(s) or OID(s): none
Person to contact for further information:
The author of this document.
Intended usage: COMMON
Author/Change controller:
"Mario Salzer" <mario@erphesfurt.de>
6.2 Security Considerations
Many evil things could happen to everbody who implemented this
protocol... (TODO)
* distinction between read-only and data manipulation calls
* sensitive information (visible transport content)
** ticketing within messages
** auth in lower level protocol
*** http basic auth
*** ssl or tls
* data types and strict typed languages
* tricking scripting languages? (known bugs only)
* compression bombs in deflate or zlib?
* drawbacks of compatibility pressure
* again recommend full xml parsers (charset issues esp)
* ...
7. Acknowledgments
Dave Winer wrote the initial specification and various revisions of
the [MINUS] protocol. Adam Megacz wrote the first Internet-Draft to
attemp to standardize the XML-RPC protocol, then eventually known as
"XMC".
8. Appendix
8.1 a DTD
8.2 SMTP Transport
8.3 Jabber Transport
9. draft TODO list
- mk fully XML compliant
- user-defined types via struct construct (advise against
namespaces and incompatible extensions like <null/> tag)
- jabber+smtp bindings in appendix
- [XML] and others are normative refs, aren't they?
- add more SHOULD server requirements for backwards compatibility
- error code registration with the IANA, above 100 user-definable??
Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2234] Crocker, D. (Ed.) and P. Overell, "Augmented BNF for
Syntax Specifications: ABNF", RFC 2234, November 1997.
[RFC3470] Hollenbeck, S., Rose, M. and L. Masinter, "Guidelines for
the Use of Extensible Markup Language (XML) within IETF
Protocols", BCP 70, RFC 3470, January 2003.
[RFC3023] Murata, M., St. Laurent, S. and D. Kohn, "XML Media
Types", RFC 3023, January 2001.
[RFC2048] Freed, N., Klensin, J. and J. Postel, "Multipurpose
Internet Mail Extensions (MIME) Part Four: Registration
Procedures", BCP 13, RFC 2048, November 1996.
[UTF8] Yergeau, F., "UTF-8, a transformation format of ISO
10646", RFC 2279, January 1998.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P. and T. Berners-Lee "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[XML] Bray, T., Paoli, J., Sperberg-McQueen, C. and E. Maler,
"Extensible Markup Language (XML) 1.0 (2nd ed)", W3C
REC-xml, October 2000, <http://www.w3.org/TR/REC-xml>.
Informative References
[MINUS] D. Winer, "XML-RPC Specification", June 1999,
<http://www.xmlrpc.org/spec>.
[FAULTC] D. Libby and others, "Specification for Fault Code
Interoperability", May 2001,
http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php
[ISO8601] "International Standardization Organisations` 8601",
...
[UTC] "Universal Time Code" (AKA "GMT"),
...
Authors' Addresses
Mario Salzer
FH Erfurt, University of Applied Sciences
Fischersand 12, 99084 Erfurt
Europe / Germany / Thuringia
email: mario@erphesfurt.de
phone: +49-361-6433638
icq: 95596825
Trademark Statement
The name "XML-RPC" is a registered trademark of Userland(?). To allow
description of a compatible protocol we named this document and the
methods and syntax it describes "XML+RPC".
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights which may cover technology that may be required to practice
this standard. Please address the information to the IETF Executive
Director.
Full Copyright Statement
Copyright (C) The Internet Society (2004). 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 this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assignees.
This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE 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.
Acknowledgment
Funding for the RFC Editor function is currently provided by the
Internet Society.
Html markup produced by rfcmarkup 1.129b, available from
https://tools.ietf.org/tools/rfcmarkup/