Skip to content

Interaction Between Sipi and DSP-API

General Remarks

DSP-API and Sipi (Simple Image Presentation Interface) are two complementary software projects. Whereas DSP-API deals with data that is written to and read from a triplestore (metadata and annotations), Sipi takes care of storing, converting and serving image files as well as other types of files such as audio, video, or documents (binary files it just stores and serves).

DSP-API and Sipi stick to a clear division of responsibility regarding files: DSP-API knows about the names of files that are attached to resources as well as some metadata and is capable of creating the URLs for the client to request them from Sipi, but the whole handling of files (storing, naming, organization of the internal directory structure, format conversions, and serving) is taken care of by Sipi.

Adding Files to DSP

A file is first uploaded to Sipi, then its metadata is submitted to DSP. The implementation of this procedure is described in DSP-API and Sipi. Instructions for the client are given in Creating File Values (for DSP-API v2) and in Adding Resources with Image Files (for API v1).

Retrieving Files from Sipi

File URLs in API v2

In DSP-API v2, image file URLs are provided in IIIF format. In the simple ontology schema, a file value is simply a IIIF URL that can be used to retrieve the file from Sipi. In the complex schema, it is a StillImageFileValue with additional properties that the client can use to construct different IIIF URLs, e.g. at different resolutions. See the knora-api ontology for details.

File URLs in API v1

In API v1, for each file value, DSP-API creates several Sipi URLs for accessing the file at different resolutions:

"resinfo": {
   "locations": [
      {
         "duration": ​0,
         "nx": ​95,
         "path": "http://sipiserver:port/knora/incunabula_0000000002.jpg/full/max/0/default.jpg",
         "ny": ​128,
         "fps": ​0,
         "format_name": "JPEG",
         "origname": "ad+s167_druck1=0001.tif",
         "protocol": "file"
      },
      {
         "duration": ​0,
          "nx": ​82,
          "path": "http://sipiserver:port/knora/incunabula_0000000002.jp2/full/82,110/0/default.jpg",
          "ny": ​110,
          "fps": ​0,
          "format_name": "JPEG2000",
          "origname": "ad+s167_druck1=0001.tif",
          "protocol": "file"
      },
      {
          "duration": ​0,
          "nx": ​163,
          "path": "http://sipiserver:port/knora/incunabula_0000000002.jp2/full/163,219/0/default.jpg",
          "ny": ​219,
          "fps": ​0,
          "format_name": "JPEG2000",
          "origname": "ad+s167_druck1=0001.tif",
          "protocol": "file"
      }
      ...
   ],
"restype_label": "Seite",
"resclass_has_location": true,

Each of these paths has to be handled by the browser by making a call to Sipi, obtaining the binary representation in the desired quality.

Authentication of Users with Sipi

Whenever a file is requested, Sipi asks the DSP-API about the current user's permissions on the given file. This is achieved by sharing the session cookie with Sipi. When the user logs in to DSP using his browser (using either V1 or V2 authentication route), a session cookie containing a JWT token representing the user is stored in the user's client. This session cookie is then read by Sipi and used to ask DSP-API for the user's image permissions.

For the session cookie to be sent to Sipi, both the DSP-API and Sipi endpoints need to be under the same domain, e.g., api.example.com and iiif.example.com.


Last update: 2022-06-22