TermWeb XML-RPC API Guide

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

Introduction

The API usage from XML-RPC directly is basically the same as when using the Java API client as described in the Javadocs. First you call initSession to create a session in TermWeb and retrieve a session ID. Then you call any of the available methods described below and pass your session ID as argument to the method. Close your session by calling the close method.

Configuration

To configure the API with TermWeb you need to add a servlet configuration to TermWeb's web.xml file:

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

And then a mapping for the servlet:

<servlet-mapping>
  <servlet-name>TermWebAPI</servlet-name>
  <url-pattern>/api</url-pattern>
</servlet-mapping>

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.

Example code

Connect to the TermWeb server

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

Create a new session (as guest user)

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

The response:

<?xml version="1.0" encoding="UTF-8"?>
<methodResponse>
  <params>
    <param><value>123456789abc</value></param>
  </params>
</methodResponse>

Close the session

<?xml version="1.0"?>
<methodCall>
   <methodName>termwebapi2.close</methodName>
   <params>
     <param><value><string>123456789abc</string></value></param>
   </params>
</methodCall>                                                                                                                                                                           

The response:

<?xml version="1.0" encoding="UTF-8"?>
<methodResponse>
  <params>
    <param><value>0</value></param>
  </params>
</methodResponse>

Types

TermWeb XML-RPC API uses only data types from the original XML-RPC specification. The data types are listed in the table below. TermWeb objects are represented by <struct>s where the first <member> contains the type of the object.

Example of a Dictionary object:

  <value><struct>
    <member>
      <name>__objtype</name>
      <value>Dictionary</value>
    </member>
    <member>
      <name>id</name>
      <value>4212</value>
    </member>
    <member>
      <name>name</name>
      <value>My Dictionary</value>
    </member>
    <member>
      <name>description</name>
      <value>A test dictionary</value>
    </member>
  </struct></value>

Methods

Error handling

If an error occurs during processing of a method, an error message containing a description of the error together with an error code is returned.

Example: Failed to invoke method getAll in class org.termweb.api.internal.XmlRpcReceiver: The session has expired. (Code:1300)

The errors and codes are as follows: