Using the jxAPI Through XML-RPC
This page is about the legacy SOAP-based jxAPI that is no longer updated or recommended for use in new projects. The documentation in this section may be outdated or inaccurate, and is provided for reference purposes only.
Journyx recommends using the REST-based API for new projects in most cases. However, at the current time, there are certain object types that are not available through the REST API.
For some applications, SOAP may be too heavy or complex, or simply inappropriate for the language or platform in use. For this kind of application, the jxAPI is also accessible through the XML-RPC protocol. (For the official specifications of XML-RPC, see http://xmlrpc.com/.)
The reasons why you might wish to use XML-RPC instead of SOAP to access the jxAPI include:
- You are developing in a language which does not require the strong type-checking of method arguments and structure members (eg. Python, Ruby, PHP)
- You are developing in a language or on a platform that has an XML-RPC client in its standard library (eg. Python, Ruby)
- You are developing for a language or platform that has no appropriate SOAP client
- You are developing for a platform with limited resources, on which a full implementation of SOAP might be impractical or impossible (eg. mobile platforms)
How the jxAPI Translates to XML-RPC
All jxAPI methods are available through XML-RPC. Data types shown in this documentation map to XML-RPC types as follows:
| Generic Type | XML-RPC Type |
|---|---|
| Integer | int |
| Long | int |
| Float | double |
| String | string |
| Boolean | boolean |
In most XML-RPC implementations this means they will be converted to an appropriate native type automatically.
Structures in the jxAPI are handled as XML-RPC struct values. In many
implementations, this means that they are passed and returned as the language's
native key/value array type (Python dict, Ruby Hash, and the like).
Server-side errors are returned as XML-RPC faults.
The server proxy URL for the XML-RPC interface to the jxAPI is:
http://server:port/jtcgi/jxapi_xmlrpc.pyc
Multicalls
The jxAPI supports the XML-RPC system.multicall method, which enables simple
batching of multiple method calls into a single request.
To perform a multicall, call the system.multicall method, passing a single
array argument which contains a list of structs representing the individual
method calls in the batch. Each struct must contain a "methodName" key naming
the method to call and a "params" key containing an array of arguments to the
method.
The return value from system.multicall is a list containing method return
values. If an item in the list is a struct, it represents a fault; if it is a
list, it contains the method return value (wrapped in this way that methods
successfully returning a struct can be distinguished from faults). Note that the
actual multicall request will only produce a fault in the case of a server
error; if one of the individual calls raises a fault processing will continue
with the rest of the batch.
While multicalls produce the same volume of network traffic and the same database load on the server as individual calls, they eliminate the HTTP request overhead of multiple requests. Since this can become rather significant, especially when SSL is in use, you are encouraged to use multicalls when it is feasible.
The original system.multicall proposal is found
here.