Application Programming Interface (API)

Introduction

This is our RESTful Application Programming Interface (API), returning JSON responses.

It provides versatile access to our open data, currently for our object records.

Primary design objectives were: 1) simple to use, and 2) fast.

This is a Beta release and we invite community feedback on this implementation.

Licences

The basic record data is dedicated to the public domain under Creative Commons Zero (CC0).
See Licence and Guidelines here.

Extended record data from the Fitzwilliam Museum is licenced as Creative Commons Attribution-ShareAlike (CC-BY-SA).
See Licence and Guidelines here.

Request parameters and values which the API understands are:

command=search | list | status [default=search]

query=<querystring> [default=*] (which means what you'd expect *=everything)

size=<nnn> [default=10, Range=1-1000]

from=<nnn> [default=0, Range=0 to maximum size of returned dataset minus 1]

dataset=<dataset_name> [default=object, no other options presently defined]

fields=<filedname>,<fieldname>,....<fieldname> [default=all]

licence=cc-0 | cc-by-sa [default=cc-0]

So a full query will look something like this ?query=dog AND cat&licence=cc-0&fields=all&dataset=object&size=200

Notes on Request Parameters and Values

Abbreviations. All parameters can be abbreviated to their first letter e.g. c= OR command=, q= OR query= etc.

Command=list. Is a 'special' case of command=search really. It still spawns a search, however, with fields=null.
The effect of this is only identifiers are returned, which is what you expect 'list' to return, i.e. a list of identifiers

fields=all A special argument to 'fields=' is 'all' (case insensitive) which is simply saying 'get me all fields'.


Notes on Fields

'identifier', 'source', and 'image'. These fields are 'injected' by the API at runtime and are not actual fields which can be queried.

How to use Search (Queries)

Default Behaviour

Search/Query=dog parrot
This, in long hand means search all indexed fields for the terms dog OR parrot.

Common Usage

Search/Query = dog AND parrot
changes the default behaviour to return results with dog AND parrot

Search/Query = dog AND (parrot cat)
precedence will honoured

Search/Query = dog AND !parrot
! = not, so this will find all records which have dog but dont have parrot

Technical Note

The API's data source is an ElasticSearch (ES) index therefore search construct follows ES's, and ultimately Lucence's, search syntaxes.


Viewing examples in a web browser

For viewing these examples I'd suggest you install the JSONView plugin in your browser (or similar, there is a port for Chrome).

A demo of 'simple and fast' is you can call the API with no request parameters and it will return results.
e.g. calling API with no parameters.

?query=parrot
Query for term 'parrot' (as stated above, command=search, fields=all, from=1, size=10, dataset=object are all implied by defaults)

?query=parrot AND Category:painting
Query for term 'parrot' limited by object classified as category painting

?command=status, or ?c=status&l=cc-by-sa
Provides a range of information about the API, most important of which is all available fields and their correct fieldnames

API versions

  • 0.85 breaking changes
    - "image": becomes "images": and
    thumbnailURI" : is always an array now (even for a single image, previous versions only ever returned one image)
    - added field "Dept": (short for department, possible values are ANT = Antiquities, CM = Coins and Medals, AA = Applied Arts, PDP = Painting drawings and Prints, MSSPB – Manuscripts and Printed Books)
  • initial versions to 0.84

Demo Android App using the API

This app was built using Tiggzi (now appery.io) as a simple demo of building a service over our API.

You can download and install it on your Android device from here (you'll need to enable installation of apps from 'unknown sources' via Phone Settings->Security).