skip to navigation skip to content

Lookup/Ibis web service API

The Lookup/Ibis web service API provides a read/write HTTP-based API for querying and manipulating data in the Lookup/Ibis database. The easiest way to use the API is with one of the supplied client libraries:

Alternatively you may access the API from a web browser or other HTTP client. The documentation above gives the URLs of the API endpoints.

The definitive API specification is in the WADL document, but this is intended to be machine-readable rather than human-readable:

For more information about WADL see:

API access

Access to the API is available over HTTPS from within the CUDN only, and may be either anonymous or use HTTP basic authentication with a username and password as follows:

Access type Username Password Access permissions
Anonymous access No HTTP Basic Authentication, or... Anonymous read-only access (similar to anonymous LDAP access), allowing all data to be read except for personal data marked as private or institution visible, and group memberships marked as visible to members or managers only.
anonymous not required
Group access A group name The group's password Read/write access with the permissions of the group. This may allow access to private personal data and group memberships.


NOTE: The following examples refer to the Lookup/Ibis test server ( The data on this server may be out of date, and is subject to being reset at any time, without notice.

The basic details of a person may be retrieved using the getPerson() API method, which is available using a URL of the following form:

Note that some web browsers may not be able to display the resulting XML, so it may be necessary to save the result and open it in a different application. Also note that the web service is only accessible from within the CUDN.

From the command line, wget and curl may also be used:

wget --secure-protocol=TLSv1 \

or equivalently, using HTTP Basic Authentication:

wget --secure-protocol=TLSv1 --http-user=anonymous --http-password= \


curl --tlsv1

or equivalently, using HTTP Basic Authentication:

curl --tlsv1 --basic --user anonymous: \

Data return format

By default all methods return XML, but JSON is also supported, and certain methods with simple return values also support returning plain text. The format returned is decided using 2 mechanisms:

  • The "Accept" header. The client may set this header to "application/xml", "application/json" or (in some cases) "text/plain" to request the data in a particular format. The MIME types "text/xml" and "text/x-json" are also supported.
  • The "format" parameter. This parameter may be added to any web service API method to request the data in a particular format. Supported values are "xml", "json" and (in some cases) "text". If set, this parameter takes precedence over any "Accept" headers.

For example:


curl --tlsv1 --header "Accept: application/json" \

Fetching additional data

All API methods that return people, institutions or groups also accept an additional fetch parameter. This is designed to allow additional related data to be returned in a single request, without the need for multiple client-server round trips. For example, the getMembers() institution method may be used to retrieve the members of an institution:

However, if you also require the email addresses of those members, it would be quite inefficient to send multiple requests to retrieve each person's email addresses. The fetch parameter makes it possible to do this in a single request:

The fetch parameter supports fetching multiple attributes (comma-separated) and reference following to fetch attributes of related objects. For example the following will also fetch each person's list of institutions and those institutions' phone numbers:,all_insts.phone_numbers

For full details of the options supported by the fetch parameter, refer to the Javadocs for PersonMethods, InstitutionMethods and GroupMethods.

Result representation

In the example above, the XML returned contains a lot of duplicated data (multiple copies of the UIS institution node) making the size of the result unnecessarily large. This can be improved by using the flattened result representation.

All API methods that return XML or JSON, also accept an optional flatten parameter, which is a boolean ("true" or "false"). This controls whether the result is returned in the default hierarchical representation or in a flattened representation.

In the flattened representation, a new entities node is present in the result, which contains 3 lists (people, institutions and groups) containing all the requested details of the distinct people, institutions or groups of relevance to the query. These entities are then referred to using their unique id values from the top level of the result, and from anywhere else in the result as needed, for example:,all_insts.phone_numbers&flatten=true

With more complex queries, the result size reduction can be much more significant.

Parsing a result in the flattened representation is more difficult, however, if you are using the client code provided this is handled automatically. The client code provided uses the flattened representation for all requests and automatically unflattens the result before returning it.

Client code

Java, Python and PHP client libraries and sample code are available from the Subversion repository:   (or browse online:

All of the API methods are in the auto-generated XxxMethods classes and return DTO objects, which include classes representing people, institutions and groups, as well as various other related entities. The following code examples show how the list of people belonging to an institution might be found:

Java example code:

import java.util.List;


ClientConnection conn = IbisClientConnection.createTestConnection();
InstitutionMethods im = new InstitutionMethods(conn);

List<IbisPerson> people = im.getMembers("UIS", null);

for (IbisPerson person : people)

Python example code:

from ibisclient import *

conn = createTestConnection()
im = InstitutionMethods(conn)

people = im.getMembers("UIS")

for person in people:

PHP example code:


require_once "ibisclient/client/IbisClientConnection.php";
require_once "ibisclient/methods/InstitutionMethods.php";

$conn = IbisClientConnection::createTestConnection();
$im = new InstitutionMethods($conn);

$people = $im->getMembers("UIS");

foreach ($people as $person)


For more complete examples, refer to the sample/test code provided in the Subversion repository.