The web API and

Detail the workings of the file.

Explain the file too, which is used by extensively.

URL routes


methods GET

returns HTML

The front page of the web service.


methods GET

returns HTML

The frequently asked questions page of the web service.


  • /account/register
  • /account/login
  • /account/logout

returns HTML

Esed for account creation via a web browser, although it would be possible to register a new account by POSTing to the registration endpoint.


  • /query/record
  • /query/collection

methods GET or POST

returns JSON

Exposes the query endpoints of the elasticsearch backend indices, so queries can be issued against it directly.

For exmaple /query/record/_search?q=* will return all records in the standard ten results at a time.


requires authorisation

methods GET

returns HTML or JSON

Provides a list of users


  • /collections/<username>
  • /collections/<username>/<collection>

methods GET

returns HTML or JSON

Provides a list of all collections, a list of collections for a user, or a particular collection for a user.


methods GET (to return the browser form) or POST

requires authorisation


For uploading from source files into collections.


not implemented

For creating new records.


  • /<username>/collections
  • /<username>/<collection>
  • /<username>/<collection>/<record>

methods GET or POST or DELETE

returns HTML or JSON

requires authorisation for retrieval of user data via GET, and for POSTs

List as JSON all collections for a given user (same as /collections/<username>).

Access information about a user, a collection, or a record. Update the records by POSTing updated versions. Delete the users, collections, records by DELETE.


methods GET

returns HTML or JSON

Anything that is not matched to a known endpoint but that can be matched to a key in the record index will cause an attempt to interpret it as an implicit value. For example, /year/2012 will attempt to return all records in the index (therefore across all collections) that have a a key called “year” where the value equals “2012”.


Any route that cannot be matched to any previous endpoint, including an implicit facet, performs the same as the /search endpoint.

Programmatic access

The API endpoints can be queried either via a web browser - which defaults to providing HTML output, of course - or programmatically by requests e.g. via cURL.

Requests for access to data operate as usual - but requests to insert data require authentication; this is achieved via API keys. Every user account has an API key assigned to it, which can be retrieved from the /username page; it can then be provided as a parameter to any request that attempts to submit data into the system - e.g. a request to the /upload endpoint.

Each endpoint can return HTML or JSON; JSON can be requested either by appending .json to the URL portion, or adding format=json to the URL parameters, or by setting the “accept” headers on your request to “application/json”.

Here is an example of retrieving some records from a collection via cURL:


Here is an example of submitting a new collection via cURL: