Endpoints

• IIIF Image API 2.x
• IIIF Image API 1.x
• Additional Features
  • Response Content Disposition
  • Bypassing the Caches
  • Processor-Specific Arguments

IIIF Image API 2.x

Documentation

• IIIF Image API 2.0
• IIIF Image API 2.1

Location

This endpoint is available at /iiif/2.

Enabling/Disabling

This endpoint can be enabled or disabled using the endpoint.iiif.2.enabled configuration key.

Compliance

Cantaloupe implements version 2.1.1 of this API, for compatibility with all 2.x clients. Compliance level is dynamically computed and declared on a per-processor basis. Most processors are "Level 2"-compliant.

Information Response Notes

sizes

An array of width/height pairs according to the formula dimension * 1/2ⁿ > endpoint.iiif.min_size. (To restrict access to only these sizes, use the endpoint.iiif.2.restrict_to_sizes configuration option.)

tiles

A list of tile sizes that will be relatively efficient to deliver, along with a list of scale factors at which each size is available.

• For images that are natively tiled, the width and height will be the smallest of the native tile dimensions, the value of the endpoint.iiif.min_tile_size configuration key, or the full image dimensions.
• For untiled images, they will be the smallest value of n for the formula: (smallest dimension) * 1/2ⁿ > endpoint.iiif.min_tile_size.

profile.formats

This list of output formats depends on the processor assigned to the format of the source image.

profile.maxArea

This value is based on the value of max_pixels in the configuration. If set to zero, it will be omitted.

profile.qualities

Depends on the qualities supported by the processor assigned to the format of the source image.

profile.supports

Dynamically computed based on the features supported by the processor assigned to the format of the source image, as well as features built into the image server itself.

Other keys (attribution, service, etc.)

See Additional Information Response Keys.

Additional Information Response Keys

Custom keys can be added to the information JSON response, such as to declare service profiles or, beginning in Image API 2.1, an optional rights statement and/or logo. The delegate script needs to implement the extra_iiif2_information_response_keys() method. An example implementation follows:

class CustomDelegate
  def extra_iiif2_information_response_keys(options = {})
    {
        'attribution' => 'Copyright My Great Organization. All rights reserved.',
        'license' => 'http://example.org/license.html',
        'logo' => 'http://example.org/logo.png',
        'service' => {
            '@context' => 'http://iiif.io/api/annex/services/physdim/1/context.json',
            'profile' => 'http://iiif.io/api/annex/services/physdim',
            'physicalScale' => 0.0025,
            'physicalUnits' => 'in'
        }
    }
  end
end

IIIF Image API 1.x

Documentation

• IIIF Image API 1.0
• IIIF Image API 1.1

Location

This endpoint is available at /iiif/1.

Enabling/Disabling

This endpoint can be enabled or disabled using the endpoint.iiif.1.enabled configuration key.

Compliance

Cantaloupe implements version 1.1 of this API, for compatibility with all 1.x clients. Compliance level is dynamically computed and declared on a per-processor basis. Most processors are "Level 2"-compliant.

Information Response Notes

tile_width and tile_height

These keys refer to tile dimensions that will be relatively efficient to deliver.

• For images that are natively tiled, these will be the smallest of the native tile dimensions, the value of the endpoint.iiif.min_tile_size configuration key, or the full image dimensions.
• For untiled images, these will be the smallest value of n for the formula: (smallest dimension) * 1/2ⁿ > endpoint.iiif.min_tile_size.

formats

This list of output formats depends on the processor assigned to the format of the source image.

qualities

Depends on the qualities supported by the processor assigned to the format of the source image.

profile

Dynamically computed based on the features supported by the processor assigned to the format of the source image, as well as features built into the image server itself.

Additional Features

All endpoints support some additional features that may not be obvious:

Response Content Disposition

The Content-Disposition HTTP response header tells clients whether to attempt to display a response entity inline or download it, perhaps accompanied by a user prompt. The endpoint.iiif.content_disposition configuration key can be used to set a value for this header in all responses. In addition, a response-content-disposition query argument can be used to suggest a value to override that on a per-request basis. This is useful for "linking to a download."

For example, the following URL will cause the image identified by some-identifier to be downloaded and saved as image.jpg:

http://my-image-server/iiif/2/some-identifier/full/full/0/default.jpg
    ?response-content-disposition=attachment%3B%20filename%3Dimage.jpg

Note that the value of the query argument must be URL-encoded. In this case, the decoded form looks like: attachment; filename=image.jpg.

Bypassing the Caches

The caches can be bypassed on a per-request basis by supplying a cache=false URL query argument. This bypasses the source, derivative, and info caches, and also omits any Cache-Control response header that may be configured, on a per-request basis, which is useful for testing and health checks.

Processor-Specific Arguments

Various processors support various additional query arguments that the IIIF Image API cannot support in the path portion of an image request URL. These are detailed in the processor documentation.