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, loosely following RESTful principles.
Detailed documentation of the available API methods is available in the WADL document (designed to be machine-readable) and in the Java client documentation (more human-readable):
For more information about WADL see:
Access to the API is available over HTTPS from within the CUDN only, and requires HTTP basic authentication with a username and password. The username and password may be specified in either of the following ways:
|Access type||Username||Password||Access permissions|
|Anonymous access||anonymous||not required||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.|
|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.|
The basic details of a person may be retrieved using the
API method, which is available using a URL of the following form:
Most standard web browsers should prompt for a username and password (enter "anonymous" and no password). 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. Note that the web service is only accessible from within the CUDN.
From the command line,
also be used, but these tools may not know about the Terena certificate
authority used to sign the site's JANET certificates. This is easily
wget --ca-certificate=JANET.ca-bundle \ --http-user=anonymous --http-password= \ https://lookup-test.csx.cam.ac.uk/api/v1/person/crsid/mug99
curl --cacert JANET.ca-bundle --basic --user anonymous: \ https://lookup-test.csx.cam.ac.uk/api/v1/person/crsid/mug99
where JANET.ca-bundle is the certificate authority bundle available here: http://www.cam.ac.uk/cs/tlscerts/certificates/JANET.ca-bundle
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.
curl --cacert JANET.ca-bundle --basic --user anonymous: \ --header "Accept: application/json" \ https://lookup-test.csx.cam.ac.uk/api/v1/person/crsid/mug99
Fetching additional data
All API methods that return people, institutions or groups also accept
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
institution method may be used to retrieve the members of an
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:
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:
In the example above, the XML returned contains a lot of duplicated data (multiple copies of the CS institution node) making the size of the result unnecessarily large. This can be fixed 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
In the flattened representation, a new
entities node is
present in the result, which contains 3 lists (
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
id values from the top level of the result, and
from anywhere else in the result as needed, for example:
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.
A Java client library and sample code is available from the Subversion repository:
All of the API methods are in the auto-generated
classes in the
package and return DTO objects in the
package, which includes classes representing people, institutions
and groups, as well as various other related entities. For example,
this code shows how the list of people belonging to an institution
might be found:
Java example code:
import java.util.List; import uk.ac.cam.ucs.ibis.client.*; import uk.ac.cam.ucs.ibis.dto.*; import uk.ac.cam.ucs.ibis.methods.*; ClientConnection conn = IbisClientConnection.createTestConnection(); InstitutionMethods im = new InstitutionMethods(conn); List<IbisPerson> people = im.getMembers("CS", null); for (IbisPerson person : people) System.out.println(person.visibleName);
Client code in other languages is available, and in each case it is structured in a similar manner to the Java client code. This means that the Java client API documentation will remain a useful reference to the client code in other languages, and the coding style is very similar.
Python example code:
from ibisclient import * conn = createTestConnection() im = InstitutionMethods(conn) people = im.getMembers("CS") for person in people: print person.visibleName
PHP example code:
<?php require_once "ibisclient/client/IbisClientConnection.php"; require_once "ibisclient/methods/InstitutionMethods.php"; $conn = IbisClientConnection::createTestConnection(); $im = new InstitutionMethods($conn); $people = $im->getMembers("CS"); foreach ($people as $person) print_r($person); ?>
For more complete examples, refer to the sample/test code provided in the Subversion repository.