University lookup service

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:

API access

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.

Examples

NOTE: The following examples refer to the Lookup/Ibis test server (lookup-test.csx.cam.ac.uk). 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:

     https://lookup-test.csx.cam.ac.uk/api/v1/person/crsid/mug99

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, wget and curl may 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 fixed: 

wget --ca-certificate=JANET.ca-bundle \
     --http-user=anonymous --http-password= \
     https://lookup-test.csx.cam.ac.uk/api/v1/person/crsid/mug99

or:

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.

For example:

     https://lookup-test.csx.cam.ac.uk/api/v1/person/crsid/mug99?format=json

or:

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 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:

     https://lookup-test.csx.cam.ac.uk/api/v1/inst/CS/members

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:

     https://lookup-test.csx.cam.ac.uk/api/v1/inst/CS/members?fetch=email

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:

     https://lookup-test.csx.cam.ac.uk/api/v1/inst/CS/members?fetch=email,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 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 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:

     https://lookup-test.csx.cam.ac.uk/api/v1/inst/CS/members?fetch=email,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

A Java client library and sample code is available from the Subversion repository:

     https://dev.csi.cam.ac.uk/svn/lookup  (or browse online: http://dev.csi.cam.ac.uk/trac/lookup/browser)

All of the API methods are in the auto-generated XxxMethods classes in the uk.ac.cam.ucs.ibis.methods package and return DTO objects in the uk.ac.cam.ucs.ibis.dto 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.