University Training Booking System web service API

The UTBS web service API provides a read/write HTTP-based API for querying and manipulating data in the UTBS database. The easiest way to use the API is with one of the supplied client libraries, which provide Java, Python and PHP code to access the API:

• Java client:   documentation  |  downloads
• Python 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 URL of the API endpoint for each API method.

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:

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

API access

Access to the API is available over HTTPS and will typically return either XML or JSON. The client libraries above use XML, and will automatically parse the XML returned from the server, converting it to objects of the appropriate class. Some parts of the API (e.g., methods that return non-public data and methods that update data) require authentication. This is done using HTTP basic authentication using the username (CRSid) and API password of a user in the UTBS database. The level of access is then controlled by the privileges granted to that user.

Examples

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

https://utbs-test.csx.cam.ac.uk/api/v1/event/39211

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

wget --secure-protocol=TLSv1 https://utbs-test.csx.cam.ac.uk/api/v1/event/39211

or:

curl --tlsv1 https://utbs-test.csx.cam.ac.uk/api/v1/event/39211

Data return format

By default most 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://utbs-test.csx.cam.ac.uk/api/v1/event/39211?format=json

or:

curl --tlsv1 --header "Accept: application/json" \
     https://utbs-test.csx.cam.ac.uk/api/v1/event/39211

Fetching additional data

All API methods that return providers, programmes, events, courses, themes, venues, bookings or institutions 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 getProgramme() method may be used to retrieve the basic details about a programme:

https://utbs-test.csx.cam.ac.uk/api/v1/programme/33748

However, if you also want all the events in the programme, this same method may be used to retrieve them:

https://utbs-test.csx.cam.ac.uk/api/v1/programme/33748?fetch=events

If you also want all the sessions for each of those events, it would be quite inefficient to send multiple requests to retrieve each event's sessions one at a time. Instead, the fetch parameter makes it possible to do this in a single request:

https://utbs-test.csx.cam.ac.uk/api/v1/programme/33748?fetch=events.sessions

where the "dot" notation in the fetch parameter is used to request additional details about the preceding entities fetched.

The fetch parameter supports fetching multiple kinds of additional data, by specifing a comma-separated list of things to fetch. For example the following will also fetch details about the programme's provider:

https://utbs-test.csx.cam.ac.uk/api/v1/programme/33748?fetch=provider,events.sessions

For full details of the options supported by the fetch parameter, refer to the detailed API documentation. For example, for programmes, see ProgrammeMethods, and for events, see EventMethods.

Result representation

Queries like those above may sometimes lead to a lot of duplication in the data returned. For example, consider the following query to return all the events in a programme, and the venues where those events are held:

https://utbs-test.csx.cam.ac.uk/api/v1/programme/33748?fetch=events.venues

Since many events are held in the same venue as other events, the data returned ends up containing multiple identical copies of the data for some venues, making it unnecessarily large. This can be avoided 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 separate lists of all the distinct entities present in the result set. 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://utbs-test.csx.cam.ac.uk/api/v1/programme/33748?fetch=events.venues&flatten=true

Which significantly reduces the size of the data returned. With more complex queries, the result size reduction can be even 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 results before returning objects of the appropriate classes.

Client code

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

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

All of the API methods are in the auto-generated XxxMethods classes and return DTO objects, which include classes representing providers, programmes, events, courses, themes, venues, people, bookings and institutions, as well as various other related entities. The following code examples show how the list of events in a programme might be found:

Java example code:

import uk.ac.cam.ucs.utbs.client.*;
import uk.ac.cam.ucs.utbs.dto.*;
import uk.ac.cam.ucs.utbs.methods.*;

ClientConnection conn = UTBSClientConnection.createTestConnection();
ProgrammeMethods pm = new ProgrammeMethods(conn);
UTBSProgramme p = pm.getProgramme(33748L, "events");

for (UTBSEvent e : p.events)
    if (e.startDate != null)
        System.out.println(e.startDate+": "+e.title);

Python example code:

from utbsclient import *

conn = createTestConnection()
pm = ProgrammeMethods(conn)
p = pm.getProgramme(33748, "events")

for e in p.events:
    if e.startDate:
        print(e.startDate.isoformat()+": "+e.title)

PHP example code:

<?php

require_once "utbsclient/client/UTBSClientConnection.php";
require_once "utbsclient/methods/ProgrammeMethods.php";

$conn = UTBSClientConnection::createTestConnection();
$pm = new ProgrammeMethods($conn);
$p = $pm->getProgramme(33748, "events");

foreach ($p->events as $e)
    if (isset($e->startDate))
        print($e->startDate->format('Y-m-d H:i:s e').": ".$e->title."\n");

?>

For more complete examples, refer to the sample/test code provided in Git: https://gitlab.developers.cam.ac.uk/uis/devops/utbs/utbs-client.