This manual refers to a future version of the software that is still in development. It may be incomplete or inaccurate and the software may change before a final release.

Endpoints

Image Endpoints

IIIF Image API 2

Documentation

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

Version 2.1.1 of this API is implemented. 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/2n > endpoint.iiif.min_size. (To restrict access to only these sizes, use the endpoint.iiif.2.restrict_to_sizes configuration option.)
tiles
Contains a tile size 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 are a multiple of the native tile dimensions no smaller than the value of the endpoint.iiif.min_tile_size configuration key.
  • For untiled images, they are based on the endpoint.iiif.min_tile_size configuration key.
profile.formats
This list of output formats depends on the processor assigned to the format of the source image.
profile.maxArea
This value reflects the settings of max_pixels and max_scale.
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, features built into the image server itself, and various other configuration options.
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

Documentation

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

Version 1.1 of this API is implemented. 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/2n > 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 these additional features:

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. 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 web browsers to download the image identified by some-identifier and save it as image.jpg:

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

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

Overriding Cache Behavior

The behavior of the caches can be overridden on a per-request basis by supplying a cache URL query argument with one of the following values:

nocache (or false [deprecated])
Completely bypasses the source, derivative, and info caches, and also omits any Cache-Control response header that may be configured.
recache
Bypasses the derivative and info caches when reading but not writing.

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.


Control Panel

The Control Panel is a web-based administrative interface with monitoring and configuration capabilities. To enable it, set endpoint.admin.enabled to true and set a username and secret in the endpoint.admin.* keys. Then, navigate to /admin in a web browser.

Changes made in the Control Panel will instantly update the application's configuration, although some changes will require a restart to take effect. They will also be written to the configuration file within a few seconds.


Health Check

A health check endpoint is available at /health. It performs several high-level functionality checks:

  1. The processing pipeline is exercised using all known-working sources and processors. This also checks that the underlying storage is online and readable.
  2. The I/O functionality of the current source cache and/or derivative cache is checked.

The JSON response includes one of three color codes:

  • GREEN indicates normal functionality.
  • YELLOW indicates a warning condition.
  • RED indicates a failure condition.

HTTP 200 is returned for GREEN status, and HTTP 500 for all other statuses.


HTTP API

The HTTP API is disabled by default, but can be enabled by setting the endpoint.api.enabled configuration option to true.

All methods require HTTP Basic authentication. Credentials are set in endpoint.api.username and endpoint.api.secret.

Invoking a POST /tasks request creates an asynchronous task identified by a UUID and submits it to a processing queue. Its status can be checked via GET /tasks/:uuid. Tasks are retained in memory, but are not persisted, so checking a task after a restart will result in a 404 Not Found response.

Status

Check application status

Request Method GET
URI /status
Expected Response Status 200 OK
Expected Response Content Type application/json

Configuration

Retrieve the configuration

Request Method GET
URI /configuration
Expected Response Status 200 OK
Expected Response Content Type application/json

Update the configuration

Request Method PUT
URI /configuration
Request Content Type application/json
Request Body Should contain the configuration keys to change:
{
  "config_key_1" : "some value",
  "config_key_2" : "some value",
  "config_key_3" : "some value"
}
(It isn't necessary to supply all keys; only the ones to change.)
Expected Response 200 OK
Notes The in-memory configuration will be updated instantly, although some key changes won't take effect until the application is restarted. Changes will also be written to the configuration file within a few seconds.

Caching

Purge invalid/expired content from all caches

Request Method POST
URI /tasks
Request Content Type application/json
Request Body
{
  "verb" : "PurgeInvalidFromCache"
}
Expected Response 204 Accepted with task URI in Location header

Purge all content relating to an individual source image from all caches

Request Method POST
URI /tasks
Request Content Type application/json
Request Body
{
  "verb" : "PurgeItemFromCache",
  "identifier" : "MyIdentifier"
}
Expected Response 204 Accepted with task URI in Location header

Purge all content from all caches

Request Method POST
URI /tasks
Request Content Type application/json
Request Body
{
  "verb" : "PurgeCache"
}
Expected Response 204 Accepted with task URI in Location header

Purge the delegate method invocation cache

Request Method POST
URI /tasks
Request Content Type application/json
Request Body
{
  "verb" : "PurgeDelegateMethodInvocationCache"
}
Expected Response 204 Accepted with task URI in Location header

Purge the info cache

Request Method POST
URI /tasks
Request Content Type application/json
Request Body
{
  "verb" : "PurgeInfoCache"
}
Expected Response 204 Accepted with task URI in Location header