Skip to content

Collections Online API

Jump to bottom
Alan Shaw edited this page Jun 16, 2016 · 33 revisions

The Collections Online API follows the JSONAPI specification.

GET /search

Search all collections.

Query parameters

Name Type Required Description
q string Yes Search term
page[number] integer No Zero indexed pagination page number to retrieve
page[size] integer No Pagination page size (default 50, max 100)
fields[TYPE] string No CSV fields to return for a resource TYPE
Facet filter parameters

(Plural parameters are optionally multiple)

To comply with the jsonapi spec these filters are also available as filter[PARAM_NAME].

All
Name Type Required Description
date[from] date No e.g. 1829, 1900-12 or 1984-04-19
date[to] date No e.g. 1829, 1900-12 or 1984-04-19
places string No Associated geographical places
Objects
Name Type Required Description
type string No e.g. Model locomotive
people string No Associated people e.g. Robert Stephenson
organisations string No ALIAS for "people" e.g. Liverpool & Manchester Railway
categories string No e.g. Locomotives and Rolling Stock
museum enum No NRM, SMG, NMeM or MSI
on_display booelan No Whether object is currently on display
location string No Object's current museum location (only if on_display)
People
Name Type Required Description
birth[place] string No Name of place person was born
birth[date] date No ALIAS for "date[from]"
death[date] date No ALIAS for "date[to]"
Documents
Name Type Required Description
type string No e.g. Engineering
people string No Associated people e.g. Robert Stephenson
organisations string No ALIAS for "people" e.g. Liverpool & Manchester Railway
archive string No Name of archive
formats string No e.g. bound volume, large format document or photograph
creator string No Name of creator
has_image boolean No Whether document has an image
image_licences string No Licence types for imagery e.g. CC BY-NC-SA

Example

GET /search?q=Charles&page[number]=3&page[size]=1 HTTP/1.1
// HTTP/1.1 200 OK
// Content-Type: application/vnd.api+json

{
  "data": [
    {
      "type": "people", // or objects or documents
      "id": "smga-people-26803",
      "attributes": {
        // Resource attributes TBC
      },
      "relationships": {
        // Resource relationships TBC
        // Format: http://jsonapi.org/format/#document-compound-documents
      },
      "meta": {
        "score": 0.076713204 // Relevance of result
      },
      "links": {
        "self": "http://www.sciencemuseum.org.uk/people/smga-people-26803" // Link to this resource
      }
    }
  ],
  "meta": {
    "total_pages": 8
  },
  "links": {
    "first": "http://www.sciencemuseum.org.uk/search?q=Charles&page[number]=0&page[size]=1",
    "last": "http://www.sciencemuseum.org.uk/search?q=Charles&page[number]=8&page[size]=1",
    "prev": "http://www.sciencemuseum.org.uk/search?q=Charles&page[number]=2&page[size]=1",
    "next": "http://www.sciencemuseum.org.uk/search?q=Charles&page[number]=4&page[size]=1"
  }
}

TODO: Define response attributes and relationships for each resource type

GET /search/objects

Search restricted to objects in the collections. See GET /search for parameters.

GET /search/people

Search restricted to people in the collections. See GET /search for parameters.

GET /search/documents

Search restricted to documents in the collections. See GET /search for parameters.

GET /objects/{id}/{slug?}

Get data for the given object ID.

Path parameters

Name Type Required Description
id string Yes Object ID
slug string No Optional (ignored) SEO friendly slug

GET /objects/{id}/relationships/objects

GET /objects/{id}/relationships/people

GET /objects/{id}/relationships/documents

Get related resources for the given object.

Path parameters

Name Type Required Description
id string Yes Object ID

GET /people/{id}/{slug?}

Get data for the given person ID. Optional (ignored) SEO friendly slug.

Path parameters

Name Type Required Description
id string Yes Person ID
slug string No Optional (ignored) SEO friendly slug

GET /people/{id}/relationships/objects

GET /people/{id}/relationships/people

GET /people/{id}/relationships/documents

Get related resources for the given person.

Path parameters

Name Type Required Description
id string Yes Person ID

GET /documents/{id}/{slug?}

Get data for the given document ID.

Path parameters

Name Type Required Description
id string Yes Document ID
slug string No Optional (ignored) SEO friendly slug

GET /documents/{id}/relationships/objects

GET /documents/{id}/relationships/people

GET /documents/{id}/relationships/documents

Get related resources for the given document.

Path parameters

Name Type Required Description
id string Yes Documents ID
Clone this wiki locally