Skip to main content

The Interface

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.

This interface uses several HTTP-based remote procedure call protocols, including SOAP (Simple Object Access Protocol), XML-RPC, and JSON-RPC. The SOAP interface is described by a WSDL (Web Services Description Language) document which provides information about data types, functions, and other interface details to the client.

As of Journyx 8.8, the jxAPI supports both RPC/Encoded and Document/Literal (wrapped) SOAP bindings, using separate endpoints. The Document/Literal (wrapped) binding is compatible with the conventions of SOAP development in newer clients such as Microsoft .NET and Apache Axis 2, and should be used for new development instead of the RPC/Encoded binding.

Both SOAP endpoints support the same types and methods, differing only in the details of how requests and responses are formed. Likewise, the XML-RPC and JSON-RPC clients have identical functionality, though because they are weakly typed their use differs in some cases from SOAP.

Access​

Since the jxAPI uses HTTP to transport calls and responses, the client will access this interface through the same server that provides the web-based user interface to Journyx. If the client can access the web server portion of the Journyx installation, it can use the jxAPI. This eliminates the need for special firewall or network configuration.

SOAP client libraries are available for most popular programming languages. This interface is developed to be compatible with Apache Axis 2 for Java and Microsoft WCF for .NET 3.5 using the wrapped document endpoint, while the RPC endpoint is intended to be backward compatible with Apache Axis 1, Microsoft SOAP 3.0 for Visual Basic, and .NET 2.x. Other SOAP clients that support WSDL with either RPC/encoded with complex types, or the document/literal wrapped convention, should also be usable.

Developers in dynamic languages or on mobile platforms may find XML-RPC or JSON-RPC more appropriate. Many languages and platforms have XML-RPC clients available, and JSON-RPC is also widely supported and can additionally be used directly anywhere there is a Javascript interpreter.

Journyx does not supply any client tools, but you can obtain the tools mentioned above as follows:

Please see the example package (distributed separately) for more information on using the jxAPI with these clients, sample code showing how to use jxAPI data types and functions, and the required type conversion DLL for Microsoft SOAP 3.0 for Visual Basic.

At its most fundamental level a valid jxAPI request consists of an HTTP request using the POST method to the jxapi.pyc site URL, where the body of the request is an XML document describing the request. The request must be a POST, not a GET request. The request document must begin with either the <SOAP-ENV> tag or else an <?xml> document identifier that looks something like:

<?xml version="1.0" encoding="utf-8"?>

If your request document does not look like that you may get an error message like "KeyError: xmlData" (in pre-8.9 version of Journyx) or else a RuntimeError with the following message: "I'm sorry, but this does not appear to be a well formatted jxAPI request."

Data Types​

The protocols used by the jxAPI are language-independent, with their own object models and data types. Typically, a client library handles the mapping between them and a specific language, so that in general, using the jxAPI is not much different than calling into "native" libraries or modules. The WSDL service description is used by SOAP client software to map native types to their SOAP representation, while XML-RPC and JSON-RPC have their own simple data models that handle fundamental types, lists, and records without additional complexity.

The following mappings between SOAP types and native types are used in this interface:

Generic TypeSOAP Type*Java (Axis 1)C#.NETVB (MS-SOAP)
Integerintegerj.m.BigIntegerintInteger
Longintegerj.m.BigIntegerintInteger
FloatdoubledoubledoubleDouble
Stringstringj.l.StringstringString
BooleanbooleanbooleanboolBoolean

Note: SOAP types are in the http://www.w3.org/1999/XMLSchema namespace

Lists are represented in SOAP by standard SOAP arrays. In most SOAP clients, including Axis and .NET, these translate to native arrays.

Records are represented by complex types defined in the WSDL schema. In Axis and .NET clients these translate to native objects with appropriately-defined accessor methods, while in Microsoft SOAP 3.0 for Visual Basic, they are COM objects defined in a type mapping DLL.

WSDL Service Description​

The WSDL service description is required by SOAP client software so that it can map SOAP types and services to constructs in the client language. WSDL documents for both SOAP bindings are automatically generated by the Journyx server when it is installed, and is available through its web server at the following URLs:

For the document wrapped binding, with .NET-compatible wrapping style:

http://server:port/<docroot>/jtime/jxapi_wsi.wsdl

For the document wrapped binding, with Axis 2-compatible wrapping style:

http://server:port/<docroot>/jtime/jxapi_wsi_j.wsdl

For the RPC encoded binding:

http://server:port/<docroot>/jtime/jxapi.wsdl

Two different document wrapped endpoints are provided because .NET and Axis use two different patterns to wrap array constructs. While you can use the .NET-style wrapping style with an Axis client, your Java code will require extra levels of indirection which can be avoided by using the alternate endpoint that wraps arrays in the way Axis expects. For clients other than .NET or Axis, either method may be preferable depending on the specific language and library you are using. (As a rule of thumb, the Axis-compatible wrapping style is likely to produce more straightforward client code if it works at all.)

This WSDL document includes a pointer to the actual SOAP server URL, so that normally you will not have to reference it directly in your client unless you wish to connect to a Journyx server other than the one the WSDL document was obtained from. The SOAP server endpoint URL is either:

http://server:port/<docroot>/jtcgi/jxapi_wsi.pyc

for the document wrapped binding with .NET-compatible wrapping style, or:

http://server:port/<docroot>/jtcgi/jxapi_wsi_j.pyc

for the document wrapped binding with Axis 2-compatible wrapping style, or

http://server:port/<docroot>/jtcgi/jxapi.pyc

for the RPC encoded binding.

For example, if Journyx is installed at https://customer-name.apps.journyx.com, the URL of the document wrapped WSDL document would be https://customer-name.apps.journyx.com/jtime/jxapi_wsi.wsdl and the endpoint would be https://customer-name.apps.journyx.com/jtcgi/jxapi_wsi.pyc.

It is recommended to always include the port number even when Journyx is running on the default web port (80).

The docroot is optional, but is often used when more than one logical "site" runs on the same host and port, or when Journyx, Inc. is hosting Journyx as an Application Service Provider (ASP). In most cases, there will be no "document root" on locally hosted sites, and the docroot part of the URL is not used.

Exception (Error) Handling​

Unless otherwise specified, all errors or internal Python exceptions will be reported by the return of a fault response through the protocol's normal means of doing so, so that a successful return indicates that no error has occurred (unless the method specification states otherwise). In most languages, the client library will translate a server fault into an exception, which will then be channeled through the native error handling mechanism. If the client language does not support exceptions, it is the application programmer's responsibility to check for a fault condition after each call to the jxAPI.

In Java with the Axis library, SOAP faults are translated to an AxisFault exception. In Visual Basic with the MS-SOAP library, you can check the err variable to see if a fault has occurred, and inspect the faultcode, faultstring, faultactor, and detail attributes of the proxy object to determine the nature of the fault.