Skip to main content

Using The jxAPI With Python

Warning: legacy API

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.

Unlike strongly type-checked languages such as Java and C#, Python can easily use the jxAPI's untyped endpoints. Since Python's standard library includes a simple proxying XML-RPC client, that means it is possible to use the jxAPI from Python without installing any additional libraries.

Requirements​

  • A Journyx installation, version 8.8 or newer
  • Python, any current version (2.x or 3.x branch)

Connecting To Journyx With XML-RPC​

The xmlrpclib package has long been a component of the Python standard library. It creates a simple method proxy to an XML-RPC endpoint such as the jxAPI, making the resulting code very straightforward. To connect to the jxAPI, import the xmlrpclib package and create a ServerProxy object using the jxAPI endpoint URL (replace the host and port specified below with the values appropriate for your installation):

import xmlrpclib

JXURL = 'http://journyx.mycompany.com:50100'

jxapi = xmlrpclib.ServerProxy(JXURL + '/jtcgi/jxapi_xmlrpc.pyc')

Now, you can call jxAPI methods using the proxy object you just created:

print(jxapi.version())  # => "8.8"

Most of the jxAPI requires authentication. To create an authenticated session, call the login method, which returns a session key. You must then pass that session key as the first argument to future jxAPI calls:

try:
    skey = jxapi.login("me", "mypassword")
except xmlrpclib.Fault as e:
    print("Login failed! %s" % (e.faultString,))
    sys.exit(0)

print(jxapi.whoami(skey))  # => "me"

Note that unlike the typed endpoints of the jxAPI, the XML-RPC endpoint supports optional arguments, so you do not need to pass the third (keep_old_sessions) argument to the login method to use the default value of 0.

Data Types​

Using the XML-RPC endpoint, the integer, float, and string types used in the jxAPI correspond to the equivalent basic types in Python; the boolean type in the jxAPI is represented by Python's True and False constants. Arrays can be passed as any Python sequence type, and are returned as lists.

Records in the jxAPI are passed and returned as Python dictionaries. Dictionaries returned from the jxAPI will normally contain all valid keys, while dictionaries you pass to the jxAPI generally need not. Note that because records are converted to plain dictionaries, there is no additional type information passed along with them to indicate what table the record is associated with; that association is implied by the called method and its parameters.

Error Handling​

Exceptions raised by the Journyx server are raised on the client side as xmlrpclib.Fault instances. The faultString attribute of the Fault contains the exception detail from the server.

Multicalls​

The jxAPI supports XML-RPC multicalls, which allow for simple batching of multiple calls into a single request to the server. To create a batch, use the xmlrpclib.MultiCall object, which accepts method calls just like the ServerProxy, but defers actually processing them until the batch is submitted. Submit the batch by calling the MultiCall object; its return value is a sequence of the return values of the calls in the batch:

batch = xmlrpclib.MultiCall(jxapi)
batch.getDefaultTimeRecord(skey)
batch.getUserMemorizedEntriesWithNames(skey, "time", "me")
batch.getUserMemorizedEntriesWithNames(skey, "expense", "me")

ret = batch()

print(ret[0])  # => <return value of getDefaultTimeRecord>
print(ret[1])  # => <user memorized time entries>
print(ret[2])  # => <user memorized expense entries>

While multicalls will not affect the performance of database-bound methods, replacing a sequence of individual calls with a multicall may reduce web request overhead significantly, especially when connecting via SSL.

For More Information​

More information on XML-RPC with Python can be found in the Python Standard Library xmlrpclib documentation.