This document describes the structure and functionality in TermWeb's XML-RPC API. For more information about XML-RPC see XML-RPC.com.

What is XML-RPC?

It's a spec and a set of implementations that allow software running on disparate operating systems, running in different environments to make procedure calls over the Internet.

It's remote procedure calling using HTTP as the transport and XML as the encoding. XML-RPC is designed to be as simple as possible, while allowing complex data structures to be transmitted, processed and returned.

Read more at http://xmlrpc.scripting.com

Data types

The XML-RPC implementation in TermWeb API uses the following data types:

XML Tag Name	Description

XML Tag Name	Description
i4 or int	A 32-bit, signed, and non-null, integer value.
boolean	A non-null, boolean value (0, or 1).
string	A string, non-null.
double	A signed, non-null, double precision, floating point number. (64 bit)
dateTime.iso8601	A pseudo ISO8601 timestamp, like 9980717T14:08:55. However, compared to a true ISO8601 value, milliseconds, and time zone informations are missing.
base64	A base64 encoded byte array.
struct	A key value pair. The keys are strings. The values may be any valid data type, including another map.
array	An array of objects. The array elements may be any valid data type, including another array. The server may return other arrays (for example String[]) or lists (using generics). However, the client will always return an Object[], because the XML-RPC protocol doesn't include between different array types.

On this page:

1 What is XML-RPC?
- 1.1 Data types
2 Getting started
- 2.1 License
- 2.2 User credentials
- 2.3 Allow access for group
- 2.4 URL Configuration
3 Connecting
- 3.1 Connecting to the API
- 3.2 Connection example
- 3.3 Session and version methods

Getting started

License

To use the TermWeb API, your TermWeb license must include XML-RPC API. You can check you license details by going to Admin View - License. XML-RPC API should be enabled.

User credentials

The API is accessed by using the same user credentials (client login, user name and password) as for normal logins. It is recommended to use one or more dedicated user account(s) for API access, since API log in will terminate any other session for that user.

Allow access for group

Users accessing the API must have API access enabled for at least one group. Edit the group and make sure Allow API access is checked.

To allow API access for all users you can edit All Users group and check Allow API access there.

URL Configuration

The connection URL for the XML-RPC API is defined in TermWeb's web.xml file

<servlet>
  <servlet-name>TermWebAPI</servlet-name>
  <servlet-class>org.termweb.api.internal.TermWebAPIServlet</servlet-class>
</servlet>
...
<servlet-mapping>
  <servlet-name>TermWebAPI</servlet-name>
  <url-pattern>/api</url-pattern>
</servlet-mapping>

If you wish to change the URL where the API is located, you can edit the <url-pattern> value and then restart TermWeb.

Connecting

Connecting to the API

These are the steps to use the API:

Connect to the API
Create a new session for a user
Call the desired methods, passing the session ID as argument
Close the session

Connection example

The TermWeb API is configured at the URI /termweb/api by default, so if your TermWeb is installed at http://myserver.example.com/termweb the API is found at http://myserver.example.com/termweb/api.

The TermWeb API uses the prefix termwebapi2 for all methods.

The API URI can be modified in the web.xml file. See Getting started.

Example code

Connect to the TermWeb server:

connect('http://myserver.example.com/termweb/api');

Create a new session for guest user:

<?xml version="1.0"?>
<methodCall>
   <methodName>termwebapi2.initSession</methodName>
   <params>
   </params>
</methodCall>

Response:

Close the session: