Skip navigation links

Package waggle.common.modules

The waggle.common.modules package contains the Waggle external API interfaces.

See:
Description

Package waggle.common.modules Description

The waggle.common.modules package contains the Waggle external API interfaces. Each interface in this package has two nested interfaces: server and client. The server interface specifies calls that can be made to the server; the client interface specifies calls that can be made from the server to the client.

Server methods (that is, methods called by client) are synchronous, so a value can be returned to the caller. Client methods, on the other, are asynchronous: The server can push data to the client by using these methods, but no value will be returned.

Communication Protocols

Simply put, the API is a simple RPC mechanism supporting multiple protocols, namely XML and JSON (other options exist for pure Java clients). This section details some sample requests that can be used as a template for all server requests. For the purposes of this document JSON clients are the primary audience.

RPC Request/Response Overview

All server requests, regardless of format, have an interface type (server or client), a module, and a method. The module and interface are concatenated in a form dictated by Java inner class naming, e.g. XConnectModule$Server. A method name is the method of the interface you wish to invoke, and arguments to a method is an array of arbitrary JSON values, with certain conventions depending on whether they are simple JSON values or objects expected to be deserialized to real Java types once they reach the server.

Required Headers

The following headers are required with every request:

X-OnTrack-APIVersion

This tells the client what version of the API is in use by the client, a sort of future-proofing. Current value is XAPI.API_VERSION.

X-OnTrack-ClientID

This is needed to differentiate different requests over the same session, for example when a user opens multiple tabs. Set this to a reasonably random value (current timestamp is fine).

Content-Type

To know what type of response the client is sending, and what the server will use in the reply. Set to application/json for JSON clients and application/xml for XML clients.

Custom Type Encoding

The server often expects complex argument types when methods are invoked. For example, the login() method of the XConnectModule$Server class expects an XLoginCredentialsInfo argument. How this is encoded depends on transport:

JSON

{"_class":"XLoginCredentialsInfo","UserName":"user name","UserPassword":"password"}

Request Structure

With few exceptions all requests are structured exactly the same way. The following is a template for how all methods are structured, whether the interface is Server or Client:

JSON

{"ModuleName":"Module$InterfaceType", "MethodName": "MethodName", "Arguments":[]}

Response Structure

Responses are always returned using the following structure:

JSON

{"returnValue":{"_class":"XLoginInfo",....},"returnStatus":"success"}

In the case where a method does not have a return value (i.e. void) only returnStatus is in the return object.

Login

Login provides a good starting point because it demonstrates one of the more complex API calls, as well as being required to be called if you want to do anything of note. It requires an argument in the request and it returns a value in the response.

JSON Request

{"ModuleName":"XConnectModule$Server","MethodName":"login","Arguments":[{"_class":"XLoginCredentialsInfo","UserName":"user name","UserPassword":"password"}]}

JSON Response

{"returnValue":{"_class":"XLoginInfo",....},"returnStatus":"success"}

Skip navigation links