Endpoints

• Image Endpoints
  • IIIF Image API 3
  • IIIF Image API 2
  • IIIF Image API 1
  • Additional Features
    • Page Selection
    • Metadata Exposure
    • Response Content Disposition
    • Overriding Cache Behavior
• Control Panel
• Health Check
• HTTP API
  • Status
  • Check application status
  • Configuration
    • Retrieve the configuration
    • Update the configuration
  • Caching
    • Purge invalid/expired content from all caches
    • Purge all content relating to an individual source image from all caches
    • Purge all content from all caches
    • Purge the info cache

Image Endpoints

IIIF Image API 3

Documentation

• IIIF Image API 3.0

Location

This endpoint is available at /iiif/3.

Enabling/Disabling

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

Compliance

Version 3.0 of this API is implemented at a compliance level of 2.

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.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.

maxArea

This value reflects the settings of max_pixels and max_scale.

Additional Information Response Keys

Custom keys can be added to the information JSON response, such as to declare service profiles or add a rights statement. The delegate class needs to implement the extra_iiif3_information_response_keys() method. An example implementation follows:

class CustomDelegate
  def extra_iiif3_information_response_keys(options = {})
    {
      'rights' => 'http://example.org/license.html',
      'service' => [
        {
          '@id': 'https://example.org/auth/login',
          '@type': 'AuthCookieService1',
          'profile': 'http://iiif.io/api/auth/1/login',
          'label': 'Log In'
        }
      ]
    }
  end
end

IIIF Image API 2

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

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/2ⁿ > endpoint.iiif.min_size. (To restrict access to only these sizes, use the endpoint.iiif.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 class 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

• 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

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/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 these additional features:

Page Selection

Some image formats support multiple pages within the same image file. When using PdfBoxProcessor or some other processor/format combination that supports multiple pages, a page number argument can be supplied in the identifier path component. See Meta-Identifiers for more information.

Metadata Exposure

Metadata embedded within most supported formats can be exposed in information responses. See Viewing Metadata.

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/3/some-identifier/full/max/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 is: 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

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 for reads but not writes.

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 configuration, although some 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. By default, it simply returns HTTP 200 OK, but if endpoint.health.dependency_check is set to true, it also performs several other checks:

1. All known-working sources are exercised to check that the underlying storage is online and readable.
2. The I/O functionality of the current source cache and/or derivative cache is checked.

This makes the for a more thorough health check, but also a slower one that may be redundant if these services are already monitored.

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. Task records 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

Configuration

Retrieve the configuration

Update the configuration

{
  "config_key_1" : "some value",
  "config_key_2" : "some value",
  "config_key_3" : "some value"
}

Caching

Purge invalid/expired content from all caches

{
  "verb" : "PurgeInvalidFromCache"
}

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

{
  "verb" : "PurgeItemFromCache",
  "identifier" : "MyIdentifier"
}

Purge all content from all caches

{
  "verb" : "PurgeCache"
}

Purge the info cache

{
  "verb" : "PurgeInfoCache"
}