Getting Started with IIIF APIs

Introduction

Over the last six months, I've been working with some new IIIF APIs that OCLC is making available for CONTENTdm, OCLC's digital collection management tool. For those who might be unfamiliar with IIIF, it stands for International Image Interoperability Framework. The purpose of IIIF is to provide standards for interoperability between image repositories in order to allow scholars rich access to image-based resources from a variety of worldwide sources.

IIIF has released specifications for four different APIs: Image, Presentation, Authentication, and Search. Currently, CONTENTdm has implemented two of these APIs: Image and Presentation. The purpose of the Image API is to provide a standardized way for repositories to deliver images. Using the Image API, clients can specify the region, size, rotation, quality characteristics, and format of the image. This allows images to be reused in different client applications. The Image API also allows clients to request basic technical information about the image, such as what sizes are available.

The Presentation API provides a standardized way of specifying the structure and layout of a complex image-based object, which can consist of one or more images. This information is typically encapsulated in what the Presentation API calls a "manifest." Each image-based digital object in CONTENTdm has a manifest that describes how the object is intended to be presented to the consumer.

Documentation on using these two APIs in CONTENTdm is located at: https://www.oclc.org/support/services/contentdm/help/customizing-website-help/other-customizations/iiif-api-support.en.html.

Image API Basics

To make a basic request for an image via the Image API, you need to specify several key bits of information:

• Base URL
• Collection ID
• Object ID
• Region
• Size
  • Height
  • Width
• Rotation
• Quality
• Format

In order to embed this image of Garden of the Gods and Pike's Peak (https://sandbox.contentdm.oclc.org/digital/collection/coll16/id/376/rec/1) from the Denver Public Library's collection into a webpage, one needs to decide on the region and the size. Knowing that we want to show the whole image and make it 1000 pixels wide, one constructs the URL below. We use the collection ID (16), object ID (376), the "full" region, width (1000), rotation (0), and quality (default) and then specify that we want a jpg. We leave off the height of the image so that the image server keeps the aspect ratio consistent. This is the resulting URL:

https://sandbox.contentdm.oclc.org/digital/iiif/coll16/376/full/1000,/0/default.jpg

The Image API can also be used to construct a square thumbnail of the page. To do this, we specify the same collection ID and object ID, the square region, a width of 150, the rotation, and quality and once again specify that we want a jpg.

https://sandbox.contentdm.oclc.org/digital/iiif/coll16/376/square/150,/0/default.jpg

One thing consumers of the IIIF Image API should note is that what makes up the "square" region is up to the image server. In the case of CONTENTdm, square images are typically an appropriately cropped area of the larger image that will still make sense to the viewer.

These are all very basic examples of using the Image API. However, the Image API can be used for more complex use cases as well. For example, it can be used to create an image lightbox like the example in the Developer Network GitHub.

Presentation API Basics

In addition to supporting the IIIF Image API, CONTENTdm supports the IIIF Presentation API. The purpose of the Presentation API is to tell clients how a digital object should be presented to users. Responses to Presentation API requests contain metadata about the object being displayed, canvas(es) to present to the user, the sequence to display canvases, what image(s) appear on each canvas, URLs to access the image to display, and metadata (typically descriptive in nature) about the individual images.

Manifests can be incredibly simple or highly complex depending on what is being presented to the user.

Making for a Request for a Manifest

To make a request for a manifest associated with a specific digital object in CONTENTdm, you need to know the base URL, the collection ID, and the object ID.

Each manifest is returned as a JSON document that contains the following information:

• ID
• Label
• Sequences
  • Canvas
• Canvases
  • Label
  • Resource
  • Service
• Metadata
  • Label
  • Value

Let’s look at a some examples of different complexity from the CONTENTdm sandbox. The first manifest we’ll look at is a manifest for an object that is a single image: https://sandbox.contentdm.oclc.org/digital/iiif-info/coll16/376.

You can see this manifest has a single canvas that contains a single resource with a pointer to a the IIIF Image API for this image.

The second manifest we’ll look at is a manifest for a postcard: https://sandbox.contentdm.oclc.org/digital/iiif-info/floodpost/290.

This manifest has two canvases: one is the front of the postcard, and one is the back of the postcard. Note how each canvas has a label that tells the consumer about it.

    {

          "height": 2099,

          "images": [

            {

              "motivation": "sc:painting",

              "on": "https://cdm10010.contentdm.oclc.org/digital/iiif/floodpost/288/canvas/c0",

              "resource": {

                "format": "image/jpeg",

                "service": {

                  "profile": "http://iiif.io/api/image/2/level1.json",

                  "@context": "http://iiif.io/api/image/2/context.json",

                  "@id": "https://cdm10010.contentdm.oclc.org/digital/iiif/floodpost/288"

                },

                "height": 2099,

                "width": 3232,

                "@id": "https://cdm10010.contentdm.oclc.org/digital/iiif/floodpost/288/full/full/0/default.jpg",

                "@type": "dctypes:Image"

              },

              "@id": "https://cdm10010.contentdm.oclc.org/digital/iiif/floodpost/288/annotation/a0",

              "@type": "oa:Annotation"

            }

          ],

          "label": "front",

          "width": 3232,

          "@type": "sc:Canvas",

          "@id": "https://cdm10010.contentdm.oclc.org/digital/iiif/floodpost/288/canvas/c0"

        }

The third manifest we’ll look at is a manifest for an issue of a digitized newspaper: https://sandbox.contentdm.oclc.org/digital/iiif-info/p10010coll1/17.

This manifest has several canvases, one for each page of the newspaper issue that has been digitized (8 total). Note the sequence section of the document. This tells the client the order in which each canvas should be presented to a user. In the case of the newspaper issue, it is this part of the manifest that keeps the images in page order.

In the next post, we'll review how to create a simple lightbox for digitized postcards using the Presentation and Image APIs.