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.
| Java Type | XML Tag Name |
| Integer | i4 or int |
| Boolean | boolean |
| String | string |
| Double | double |
| java.util.Date | dateTime.iso8601 |
| byte[] | base64 |
| java.util.Map | struct |
| Object[] java.util.List | array |
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
| Method name | Arguments | Returns | Description |
|---|---|---|---|
| getTermWebVersion | None | Version string | Returns the version string from TermWeb |
| initSession | None | Session ID | Creates a session as auto-login guest |
| initSession | client, user, password | Session ID | Creates a session as for specified client and user |
| close | sessionID | - | Closes the session |
| getAll | sessionID, object type | Array of TermWeb objects | Retrieves all available objects of specified type. The possible types are dictionary, domain |
| setAllSelected | sessionID, object type | - | Selects all available objects of specified type. The possible types are section, domain |
| setSelected | sessionID, object type, ID | - | Select object with specified type and ID. The possible types are dictionary, language, domain, section |
| setSelected | sessionID, object type, array of IDs | - | Select all objects with specified type and IDs. The possible types are domain, section |
| getSelected | sessionID, object type | The selected object | Returns the selected object of specified type. The possible types are dictionary |
| getIndexTerms | sessionID, search string | A list of index terms | Returns the index terms that matches the search expression. |
| getIndexTerms | sessionID, search condition map | A list of index terms | Returns the index terms that matches the search conditions |
| getIndexTerms | sessionID, search condition map, target language | A list of index terms | Returns index terms for the specified target language corresponding to the index terms that matches the search conditions |
| getConceptEntry | sessionID, conceptEntryID | A concept entry | Returns the concept entry with specified ID. |
| getSourceLanguage | sessionID | A language code | Returns the ISO 639-2 language code for the currently selected source language |
| setSourceLanguage | sessionID, language code | - | Sets the currently selected source language |
| getObject | sessionID, object type, id | A TermWeb object | Returns the object with specified type and id |
| getObjectByName | sessionID, object type, name | A TermWeb object | Returns the object with specified type and name |
| create | sessionID, object | - | Creates a new TermWeb object in the current context |
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:
...
The client account is disabled
...
| Child pages (Children Display) | ||||
|---|---|---|---|---|
|