RFC 023: Images endpoint

This RFC proposes an initial images endpoint for the catalogue API, allowing for searching and fetching images from the visual collections.

Last modified: 2020-05-06T15:53:14+01:00

Context and requirements

• There is a new entity in the catalogue API: Image. These are conceptual, like works, and consist of images from the visual collections and interesting images from inside books and other materials.

• We want to be able to search for images, and to fetch specified images.

• The images endpoint should be consistent with the works endpoint.

Proposal

The initial images endpoint will be in beta, and therefore will be liable to have breaking changes made without a version bump.

Image display model

{
  "id": String,
  "locations": List[DigitalLocation],
  "source": {
    "id": String,
    "type": "Work"
  },
  "type": "Image"
}

This is intentionally minimal at this point as we decide what fields an image should have; it's what is needed to render the panel on search results.

Single image

GET /catalogue/v2/images/:image_id

Query params

• include - optional list of fields, as with works endpoint

  • visuallySimilar - includes a list of visually similar works

Multiple images

GET /catalogue/v2/images

Query params

• query - text search query

• include - optional list of extra fields not including visuallySimilar

• locations.license - license to filter for

• page

• pageSize