Names API

The following section describes the Names REST API.

Record Identifiers

Every record within names is given a unique identifier, which also acts as a resolvable URL. Each record therefore is treated as a resource.

Identifiers take the following form:

http://{identifier provider url}/{individual OR institution}/{internal id}

For example within the names service environment identifiers take the following form:

Search

Records can be searched over using the names search API. Search queries are POSTed to the web application as follows:

http://names.mimas.ac.uk/search

The query accepts the following parameters:

Name

Description:

Provides search over names associated with individuals or institutions.

Accepts:

Examples:

http://names.mimas.ac.uk/search?name=cox
http://names.mimas.ac.uk/search?name=cox b
http://names.mimas.ac.uk/search?name=cox or hawking
http://names.mimas.ac.uk/search?name="cox or hawking"
http://names.mimas.ac.uk/search?name=hawk*
http://names.mimas.ac.uk/search?name=*hawk
http://names.mimas.ac.uk/search?name=*hawk*

Affiliation

Description:

Provides search over names of institutions entities are associated with.

Accepts:

Examples:

http://names.mimas.ac.uk/search?affiliation=manchester
http://names.mimas.ac.uk/search?affiliation=manchester or york
http://names.mimas.ac.uk/search?affiliation="University of Manchester"

Fieldofactivity

Description:

Provides search over fields of activities associated with entities

Accepts:

Examples:

http://names.mimas.ac.uk/search?fieldofactivity=physics
http://names.mimas.ac.uk/search?fieldofactivity=physics or maths
http://names.mimas.ac.uk/search?fieldofactivity="Electrical and Electronic Engineering"

Identifier

Description:

Provides search over external identifiers assigned to entities

Accepts:

Examples:

http://names.mimas.ac.uk/search?identifier="ISNI 0000 0001 2409 6156"
http://names.mimas.ac.uk/search?identifier=http://eprints.uwe.ac.uk/id/person/ext-jennifer.hill@uwe.ac.uk

Mixing parameters

The parameters above can be used in conjunction:

http://names.mimas.ac.uk/search?name=hill j&fieldofactivity="Geography and Environmental Studies"
http://names.mimas.ac.uk/search?name=cox b&affiliation="University of Manchester"
http://names.mimas.ac.uk/search?fieldofactivity=physics
http://names.mimas.ac.uk/search?affiliation="University of Manchester"

Start

In addition, to enable paging through results, the start parameter can be used:

http://names.mimas.ac.uk/search?name=smith&start=50

Output format

There are three output formats available for both search results and individual records:

The client application can specify which of these formats they wish to recieve for a request by specifying it in the Accepts of the header in their HTTP request.