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

GET /search/people

GET /search/documents

Search restricted to particular resource type. See GET /search for parameters.

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

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

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

Get data for the given resource ID.

Path parameters

Name Type Required Description
id string Yes Resource 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 /people/{id}/relationships/objects

GET /people/{id}/relationships/people

GET /people/{id}/relationships/documents

GET /documents/{id}/relationships/objects

GET /documents/{id}/relationships/people

GET /documents/{id}/relationships/documents

Get related resources for the given resource ID. Note these are required by the JSONAPI spec but won't be used by the website

Path parameters

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