This document is a specification for the XML-RPC Introspection protocol. XML-RPC Introspection is a facility of XML-RPC clients and servers that enables a client to learn from a server what XML-RPC methods it implements.
XML-RPC Introspection is not part of the XML-RPC standard. It is not part of any recognized standard. This document merely describes a de facto standard that has been implemented by lots of XML-RPC clients and servers. Various other documents have existed that describe this protocol, but this document is more specific than any of them.
XML-RPC Introspection was invented around 2001 by Edd Dumbill.
Bryan Henderson (bryanh@giraffe-data.com) wrote and maintains this document.
This document was first published in November 2007.
This document does not presume to prescribe to anyone how to implement an XML-RPC client or server, or whether to call an implementation XML-RPC Introspection, especially since most of the software to do so was already written and in use before this document existed. Rather, its main goal is to describe current practice. If you know of implementations that vary from this specification, let Bryan know so he can update the specification.
A secondary goal of this specification is to provide a common recommendation for new implementations of XML-RPC clients and servers, to maximize the chance that independent designers will arrive at compatible designs.
This specification specifies XML-RPC Introspection Version 1.
For the purposes of the getCapabilities method, cite XML-RPC Introspection as follows:
XML-RPC Introspection consists of 3 XML-RPC methods. For a server to provide XML-RPC Introspection service means it has these methods.
A server might have XML-RPC Introspection service and yet keep some or all of its methods secret. I.e. XML-RPC Introspection does not require a server to report on its methods; only that for the ones that it does, it report a certain way.
This method returns a list of the methods the server has, by name.
system.listMethods.
There are no parameters.
The result is an XML-RPC array of XML-RPC strings. The value of each element is the name of a method that the server implements. The introspection methods are not excluded.
Each element is unique (the same name doesn't appear twice in the list).
It is not required that the list be a complete list of the methods the server implements; i.e. the server may choose to keep some secret. But it is required that any method in the list actually exist on the server -- the server may not fail an RPC with a "no such method" error if its name appears in this list.
Call:
<methodCall>
<methodName>system.listMethods</methodName>
<params></params>
</methodCall>
Response:
<methodResponse>
<params>
<param>
<value><array><data>
<value>
<string>system.listMethods</string>
</value>
<value>
<string>system.methodSignature</string>
</value>
<value>
<string>system.methodHelp</string>
</value>
<value>
<string>system.multicall</string>
</value>
<value>
<string>system.shutdown</string>
</value>
<value>
<string>sample.add</string>
</value>
</data></array></value>
</param>
</params>
</methodResponse>
This method returns a description of the argument format a particular method expects.
system.methodSignature.
The method takes one parameter, an XML-RPC string. Its value is the name of the XML-RPC method about which information is being requested.
The result is an XML-RPC array, with each element representing one method signature. The array is a list of the signatures of the method. There are no duplicate signatures. The list does not necessarily contain all possible signatures (it would not be realistic to expect it to do so, because some methods are so flexible that they have an infinite set of signatures). We refer to the signatures that the server is willing to report as the signatures that the introspection machinery "knows."
A signature is a description of parameter and result types for a call to a method. A method can have multiple signatures; for example a method might take either a host name and port number or just a host name (and default the port number).
The array entry that represents a signature is an array of XML-RPC strings, with at least one element. The first element tells the type of the method's result. The rest tell the types of the method's parameters, in order.
Each of these strings identifies an XML-RPC type by the XML element name for it. For example, if the parameter is an XML-RPC string, the value is string. Where an XML-RPC type has multiple equivalent XML element names, the signature may use any one of them. For example, the XML-RPC integer type can be represented either by <int> or <i4>.
If the server implements an extension to XML-RPC that recognizes additional data types, the XML-RPC Introspection definition should be considered extended accordingly.
The signature may alternatively use an upper case translation of the XML element name. (This is a really bad idea, but we've seen a server do it, so if a client wants to be maximally interoperable, it must recognize this alternative).
The system.methodSignature result may indicate that the introspection machinery simply does not know what signatures the method has. We call this the "I don't know" result. The "I don't know" result consists of an XML-RPC string with value undef. Alternatively, the result can be anything at all that is not an XML-RPC array. The string undef is preferred, but many servers exist that generate other things instead.
Note that an empty array is not a valid result. (Considering that if a method has 10 signatures and the server chooses not to report 5 of them, it can just return an array of 5 elements, it's logical that if it chooses not to report any of them, it would return an empty array. But the original designer of XML-RPC Introspection didn't go that way).
Note that a signature does not give details of a complex type; it just gives the basic XML-RPC type -- array or structure. E.g. if the result of a method is a structure with members "foo" and "bar", system.methodSignature gives the type of the result simply as structure.
The RPC fails if the server does not have a method by the indicated name, or does not want to admit that it does. But if the method name appears in the response to system.listMethods, the RPC does not fail this way.
Call:
<methodCall>
<methodName>system.methodSignature</methodName>
<params>
<param><value>
<string>sample.add</string>
</value></param>
</params>
</methodCall>
Response:
<methodResponse>
<params>
<param>
<value><array><data>
<value><array><data>
<value>
<string>int</string> <!-- return value -->
</value>
<value>
<string>int</string> <!-- 1st param -->
</value>
<value>
<string>int</string> <!-- 2nd param -->
</value>
</data></array></value>
</data></array>
</value></param>
</params>
</methodResponse>
This method returns a text description of a particular method.
system.methodHelp.
The method takes one parameter, an XML-RPC string. Its value is the name of the XML-RPC method about which information is being requested.
The result is an XML-RPC string. The value of that string is a text description, for human use, of the method in question.
The server may give as much or as little detail as it wants, including an empty string.
The string may alternatively contain HTML markup (i.e. not be precisely text). A client is not required to recognize it as such; i.e. it can leave the HTML markup for human interpretation like the rest of the string's value.
The RPC fails if the server does not have a method by the indicated name, or does not want to admit that it does. But if the method name appears in the response to system.listMethods, the RPC does not fail this way.
Call:
<methodCall>
<methodName>system.methodHelp</methodName>
<params>
<param><value>
<string>sample.add</string>
</value></param>
</params>
</methodCall>
Response:
<methodResponse>
<params>
<param><value>
<string>This method adds two integers together
</string>
</value></param>
</params>
</methodResponse>