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:

• Java client:    documentation  |  downloads
• Python 3 client:    documentation  |  downloads
• PHP client:    documentation  |  downloads

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:

• application.wadl

For more information about WADL see:

• http://en.wikipedia.org/wiki/Web_Application_Description_Language
• http://www.w3.org/Submission/wadl/

Swagger 2.0 and OpenAPI 3.0 specifications for the API are also available, however these are currently limited to the read-only parts of the API:

• Swagger 2.0:    JSON  |  YAML
• OpenAPI 3.0:    JSON  |  YAML

API access

Anonymous access to the API is available over HTTPS from within the CUDN only. Otherwise authenticated access using HTTP basic authentication over HTTPS is available from anywhere, using a group name 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. This is only available from within the CUDN.
	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. This is available outside the CUDN.

Anonymous access to the lookup LDAP and API is strongly discouraged, and newly created services should use authenticated access either via the API gateway or authenticated/bound LDAP connections. Old CUDN services may still have anonymous access, but newly added devices to the network may not be added to the anonymous access list.

The long term intention for the service is to remove the ability for anonymous access to the Lookup service.

Examples

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.srv.uis.cam.ac.uk/api/v1/person/crsid/mug99

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 anonymous access to the web service API is only available from within the CUDN.

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

wget --secure-protocol=TLSv1 \
     https://lookup-test.srv.uis.cam.ac.uk/api/v1/person/crsid/mug99

or equivalently, using HTTP Basic Authentication:

wget --secure-protocol=TLSv1 --http-user=anonymous --http-password= \
     https://lookup-test.srv.uis.cam.ac.uk/api/v1/person/crsid/mug99

or:

curl --tlsv1 https://lookup-test.srv.uis.cam.ac.uk/api/v1/person/crsid/mug99

or equivalently, using HTTP Basic Authentication:

curl --tlsv1 --basic --user anonymous: \
     https://lookup-test.srv.uis.cam.ac.uk/api/v1/person/crsid/mug99

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.srv.uis.cam.ac.uk/api/v1/person/crsid/mug99?format=json

or:

curl --tlsv1 --header "Accept: application/json" \
     https://lookup-test.srv.uis.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.srv.uis.cam.ac.uk/api/v1/inst/UIS/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.srv.uis.cam.ac.uk/api/v1/inst/UIS/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.srv.uis.cam.ac.uk/api/v1/inst/UIS/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 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:

https://lookup-test.srv.uis.cam.ac.uk/api/v1/inst/UIS/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

Java, Python and PHP client libraries and sample code are available from the GitLab repository:

https://gitlab.developers.cam.ac.uk/uis/devops/ibis/ibis-client

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;

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("UIS", null);

for (IbisPerson person : people)
    System.out.println(person.visibleName);

Python example code:

from ibisclient import *

conn = createTestConnection()
im = InstitutionMethods(conn)

people = im.getMembers("UIS")

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("UIS");

foreach ($people as $person)
    print($person->visibleName . "\n");

?>

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

Using the API from other languages

The simplest way to use the API from a different programming language, for which an official UIS client library is not available, is to use the Swagger/OpenAPI description of the API. Swagger provides tools to generate client code in a wide variety of programming languages, and many pre-built Swagger/OpenAPI clients are also available. For example, in perl you might use the OpenAPI::Client module.

Perl example code:

use strict;
use warnings;
use OpenAPI::Client;

my $client = OpenAPI::Client->new('https://lookup-test.srv.uis.cam.ac.uk/swagger-2.0.json');

my $tx = $client->Institution_getMembers({instid => 'UIS'});
my $people = $tx->res->dom->find('people')->first;

for my $person ($people->children->each) {
    print $person->find('visibleName')->first->content . "\n";
}

Note that currently the Swagger/OpenAPI specifications for the Lookup API only support the read-only methods of the API — i.e., it is possible to query data, but it is not currently possible to modify data using an OpenAPI client.