Overview (TermWeb API 2.10)

Packages
Package	Description
org.termweb.api	Base package for TermWeb API classes.
org.termweb.api.common	Common constants and definitions for API methods.
org.termweb.api.data	Contains data classes used in the API.
org.termweb.api.data.def	Contains data objects for dictionary definitions.
org.termweb.api.data.entry	Contains data objects for concept and term entries.
org.termweb.api.data.files	Contains data objects for virtual files, and export and import operations.
org.termweb.api.data.search	Contains data objects for searching and filtering.
org.termweb.api.data.user	Contains data objects for users, groups and permissions.
org.termweb.api.data.workflow	Contains data classes for Projects and Workflows.
org.termweb.api.internal	Server side classes.

This is the API description for TermWeb v3.17.2, please read the introduction below to learn about the packages and functions of the API that are intended to be used in TermWeb application development.

Introduction to the TermWeb API

With the TermWeb API you can perform many of the tasks possible from within TermWeb, for example:

Searching for terms and related data
Creating, editing and deleting term and concept entries

The API is using XML-RPC as transport protocol, which allows it to be used from various platforms and over internal or external networks.

How to start developing TermWeb applications

Here are some basic pointers that should help you to identify important parts in this API documentation that are usually required in TermWeb application development:

Connecting

To connect to a TermWeb server from another Java system, you use a client object to obtain a session object. The session object provides all methods available in the API. User authentication and authorization is performed for all method calls, so the API user must be granted the appropriate permissions in TermWeb to be able to use certain methods. Specifically, the user's group must have been given the "Allow API access" permission.

The client object is defined by the TermWebClient interface, which is implemented in the XmlRpcTermWebClient.

To create a new external client object you call XmlRpcTermWebClient.connect(url), where url is the url for your TermWeb server's XML-RPC interface.

From the client object you call one of the initSession() methods with necessary credentials to get the TermWebSession object, which you use to call methods in TermWeb.

TermWeb data objects

TermWeb data objects that are returned from or passed in as parameters to the methods in the session object implements the TermWebObj interface. The methods in the interface are:

getID - Returns the unique ID of the object.
getName - Returns the name of the object.
validate - Performs a validation of the object to check that it contains valid data and is possible to save in the database.

The different data object classes are located in the subpackages of org.termweb.api.data. Helper classes, such as enums and other static definitions used by the data object classes, are also located in these packages.

Creation of new data objects are done by simply calling the empty constructor for the appropriate class, filling necessary data in the object, and passing the object to the TermWebSession.create() method. The object need to pass the validation method and may in some cases be dependent on other objects.

TermWeb IDs

The TermWebID represents the unique ID for an object in TermWeb. The ID is retrived from the TermWebObj.getID() method for each data object, and is also returned from, and passed as parameter to many of the methods in the session object.

The ID is internally represented as a long value, which is wrapped in a TermWebID.

The ID is guaranteed to be unique among objects of the same type (i.e. same data object class). It is not guaranteed to be unique throughout the system.

Additional request parameters

Since API version 2.9 (TermWeb 3.16) you can specify additional parameters for generic method calls. These parameters are used to modify what data should be returned for objects. Parameters can be added to the type name value in all generic methods, in the same format as a URL query string.

ConceptEntry?field1=value1&field2=value2&field3=value3...

When using the XmlRpcTermWebSession, you can set parameters with the setProperty method.

To include metadata in objects, set the property metadata to true.

Cleaning up

When your application is done using the API it should close the connection and release the resources. This is done by calling TermWebClient.close(TermWebSession) to close the session object. You can later start a new session from the same client object, or you can disconnect the client object from the server with TermWebClient.disconnect() to release resources taken by the client object.