Ga naar hoofdinhoud

Integration Layer API specification

Work in progress

This document is for illustration and discussion only. It has no official standing.

Introduction​

This document defines the API specification for the exchange of heritage information between integration layers and presentation layers within the Dutch Digital Heritage Network (NDE). It standardises the interface an integration layer exposes to a presentation layer, by defining the rules, data models and endpoints for the most important interactions between the two.

The API specification is divided into two sub specifications: one for REST and one for GraphQL. An integration layer can choose which sub specification it follows. At this stage the focus is on REST. The GraphQL specification has not been developed yet: its pages are a placeholder for a future version.

The specification helps both kinds of developer. Integration layer developers can build an integration layer API more easily, because they can follow the specification instead of designing their own. Presentation layer developers can build a presentation layer once and reuse it with any integration layer that follows the same specification, reducing the need for custom integrations.

Definitions​

  1. An integration layer integrates heritage information from multiple data providers and exposes it through an API for use by one or more presentation layers.
  2. A presentation layer uses heritage information from integration layers and makes it accessible to end users, e.g. via websites or mobile apps.

Audience​

This document is intended for:

  1. Integration layer developers building compliant APIs.
  2. Presentation layer developers building generic clients that work across various integration layers.

Conformance​

The keywords MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, SHOULD, and SHOULD NOT are to be interpreted as described in RFC 2119, when, and only when, they appear in all capitals, as shown here.

To do
  • Add references to the gedragsprofielen digitaal erfgoed.
  • Make a clean separation between the specification of the interface and the behaviour of the integration layer (what it must or should do).
  • Include a 'Metamodel Informatiemodellering' (MIM), explaining the information model on which the API is grounded.
  • Describe the integration with the IIIF APIs, for interacting with media objects and their metadata. For example:
    • An integration layer should be able to publish its own IIIF collection(s) with manifests from data providers
    • An integration layer should retrieve and cache media object dimensions from IIIF info.json files from data providers so that presentation layers do not have to request these real-time