Image API 2.0

Status of this Document

This Version: 2.0.0

Latest Stable Version: 3.0.0

Previous Version: 1.1

Editors:

• Michael Appleby , Yale University
• Robert Sanderson , Stanford University
• Stuart Snydman, Stanford University
• Jon Stroop , Princeton University Library
• Simeon Warner , Cornell University

Copyright © 2012-2024 Editors and contributors. Published by the IIIF Consortium under the CC-BY license, see disclaimer.

Abstract

This document describes an image delivery API proposed by the International Image Interoperability Framework (IIIF) group. The IIIF Image API specifies a web service that returns an image in response to a standard HTTP or HTTPS request. The URI can specify the region, size, rotation, quality characteristics and format of the requested image. A URI can also be constructed to request basic technical information about the image to support client applications. This API was conceived of to facilitate systematic reuse of image resources in digital image repositories maintained by cultural heritage organizations. It could be adopted by any image repository or service, and can be used to retrieve static images in response to a properly constructed URI.

Please send feedback to iiif-discuss@googlegroups.com

1. Audience and Scope

This document is intended for architects and developers building applications that share and consume digital images, particularly from cultural heritage institutions, museums, libraries and archives. Target applications include:

• Digital image repositories and distributed content networks.
• Image focused web applications, such as pan/zoom viewers, book-readers, etc.
• Client applications using image content for analysis or comparison.

This specification concerns image requests by a client, but not management of the images by the server. It covers how to respond to the requests given in a particular URI syntax, but does not cover methods of implementation such as rotation algorithms, transcoding, color management, compression, or how to respond to URIs that do not conform to the specified syntax. This allows flexibility for implementation in domains with particular constraints or specific community practices, while supporting interoperability in the general case.

2. URI Syntax

The IIIF Image API can be called in two ways:

• Request an image, which may be part of a larger image.
• Request a description of the image characteristics and functionality available for that image.

Both convey the request’s information in the path segments of the URI, rather than as query parameters. This makes responses easier to cache, either at the server or by standard web-caching infrastructure. It also permits a minimal implementation using pre-computed files in a matching directory structure.

There are four parameters shared by the requests, and other IIIF specifications:

The combination of these parameters forms the image’s Base URI and identifies the underlying image content. It is constructed according to the following URI Template (RFC6570):

{scheme}://{server}{/prefix}/{identifier}

When the base URI is dereferenced, the interaction should result in the Image Information document. It is recommended that the response be a 303 status redirection to the Image Information document’s URI. Implementations may also exhibit other behavior for the base URI beyond the scope of this specification in response to HTTP request headers and methods.

To allow for extensions, this specification does not define the server behavior when it receives requests that do not match either the Base URI or one of the described URI syntaxes below.

2.1. Image Request URI Syntax

The IIIF Image API URI for requesting an image must conform to the following URI Template:

{scheme}://{server}{/prefix}/{identifier}/{region}/{size}/{rotation}/{quality}.{format}

For example:

http://www.example.org/image-service/abcd1234/full/full/0/default.jpg

The parameters of the Image Request URI include region, size, rotation, quality and format, which define the characteristics of the returned image. These are described in detail in Image Request Parameters.

2.2. Image Information Request URI Syntax

The URI for requesting image information must conform to the following URI Template:

{scheme}://{server}{/prefix}/{identifier}/info.json

For example:

http://www.example.org/image-service/abcd1234/info.json

The scheme, server, prefix and identifier components of the information request must be identical to those for the image request described above for the image content that the Image Information document describes. The Image Information document is described in detail in the Image Information section.

3. Identifier

The API places no restrictions on the form of the identifiers that a server may use or support. All special characters (e.g. ? or #) must be URI encoded to avoid unpredictable client behaviors. The URI syntax relies upon slash (/) separators so any slashes in the identifier must be URI encoded (also called “percent encoded”). See the additional discussion in URI Encoding and Decoding.

4. Image Request Parameters

All parameters described below are required for compliant construction of a IIIF Image API URI. The sequence of parameters in the URI must be in the order described below. The order of the parameters is also intended as a mnemonic for the order of the operations by which the service should manipulate the image content. Thus, the requested image content is first extracted as a region of the complete image, then scaled to the requested size, mirrored and/or rotated, and finally transformed into the color quality and format. This resulting image content is returned as the representation for the URI. Image and region dimensions in pixels are always given as an integer numbers. Intermediate calculations may use floating point numbers and the rounding method is implementation specific. Some parameters, notably percentages, may be specified with floating point numbers. These should have at most 10 decimal digits and consist only of decimal digits and “.” with a leading zero if less than 1.0.

4.1. Region

The region parameter defines the rectangular portion of the full image to be returned. Region can be specified by pixel coordinates, percentage or by the value “full”, which specifies that the entire image should be returned.

If the request specifies a region which extends beyond the dimensions reported in the Image Information document, then the service should return an image cropped at the image’s edge, rather than adding empty space.

If the requested region’s height or width is zero, or if the region is entirely outside the bounds of the reported dimensions, then the server should return a 400 status code.

Examples:

1 size=full .../full/full/0/default.jpg	2 region=125,15,120,140 .../125,15,120,140/full/0/default.jpg
3 region=pct:41.6,7.5,40,70 .../pct:41.6,7.5,40,70/full/0/default.jpg	4 region=125,15,200,200 .../125,15,200,200/full/0/default.jpg N.B. Returned image is 175,185 px
5 region=pct:41.6,7.5,66.6,100 .../pct:41.6,7.5,66.6,100/full/0/default.jpg N.B. Returned image is 175,185 px

4.2. Size

The size parameter determines the dimensions to which the extracted region is to be scaled.

If the resulting height or width is zero, then the server should return a 400 (bad request) status code.

The image server may support scaling above the full size of the extracted region.

Examples:

1 size=full .../full/full/0/default.jpg	2 size=150, .../full/150,/0/default.jpg	3 size=,150 .../full/,150/0/default.jpg
4 size=pct:50 .../full/pct:50/0/default.jpg	5 size=225,100 .../full/225,100/0/default.jpg	6 size=!225,100 .../full/!225,100/0/default.jpg N.B. Returned image is 150,100 px

4.3. Rotation

The rotation parameter specifies mirroring and rotation. A leading exclamation mark (“!”) indicates that the image should be mirrored by reflection on the vertical axis before any rotation is applied. The numerical value represents the number of degrees of clockwise rotation, and may be any floating point number from 0 to 360.

A rotation value that is out of range or unsupported should result in a 400 status code.

In most cases a rotation will change the width and height dimensions of the returned image. The service should return an image that contains all of the image contents requested in the region and size parameters, even if the dimensions of the returned image file are different than specified in the size parameter. The image contents should not be scaled as a result of the rotation, and there should be no additional space between the corners of the rotated image contents and the bounding box of the returned image content.

For rotations which are not multiples of 90 degrees, it is recommended that the client request the image in a format that supports transparency, such as PNG, and that the server return the image with a transparent background. There is no facility in the API for the client to request a particular background color or other fill pattern.

Examples:

1 rotation=0 .../full/full/0/default.jpg	2 rotation=180 .../full/full/180/default.jpg
3 rotation=90 .../full/full/90/default.jpg	4 rotation=22.5 .../full/full/22.5/default.png
5 rotation=!0 .../full/full/!0/default.jpg	6 rotation=!180 .../full/full/!180/default.jpg

4.4. Quality

The quality parameter determines whether the image is delivered in color, grayscale or black and white.

The default quality exists to support level 0 compliant implementations that may not know the qualities of individual images in their collections. It also provides a convenience for clients that know the values for all other parameters of a request except the quality (e.g. .../full/120,/90/{quality}.png to request a thumbnail) in that a preliminary image information request that would only serve to find out which qualities are available can be avoided.

A quality value that is unsupported should result in a 400 status code.

Examples:

1 quality=default .../full/full/0/default.jpg	2 quality=color .../full/full/0/color.jpg
3 quality=gray .../full/full/0/gray.jpg	4 quality=bitonal .../full/full/0/bitonal.jpg

4.5. Format

The format of the returned image is expressed as an extension at the end of the URI.

A format value that is unsupported should result in a 400 status code.

Examples:

1. .../full/full/0/default.jpg
2. .../full/full/0/default.png
3. .../full/full/0/default.tif

4.6. Order of Implementation

The sequence of parameters in the URI is intended as a mnemonic for the order in which image manipulations are made against the full image content. This is important to consider when implementing the service because applying the same parameters in a different sequence will often result in a different image being delivered. The order is critical so that the application calling the service reliably receives the output it expects.

The parameters should be interpreted as if the the sequence of image manipulations were:

Region THEN Size THEN Rotation THEN Quality THEN Format

If the rotation parameter includes mirroring (“!”), the mirroring is applied before the rotation.

1 region=125,15,120,140 size=90, rotation=!345 quality=gray .../125,15,120,140/90,/!345/gray.jpg

4.7. Canonical URI Syntax

There are many ways in which the same image can be described using the different forms of the parameters. While it is useful for clients to be able to express their requests in a convenient form, there are several reasons why a canonical URI syntax is desirable:

• It enables static, file-system based implementations, which will have only a single URI at which the content is available.
• Caching becomes significantly more efficient, both client and server side, when the URIs used are the same between systems and sessions.
• Response times can be improved by avoiding redirects from a requested non-canonical URI syntax to the canonical syntax by using the canonical form directly.

In order to support the above requirements, clients should construct the image request URIs using the following canonical parameter values where possible. Image servers may redirect the client to the canonical URI from a non-canonical equivalent.

When the client requests an image, the server may add a link header to the response that indicates the canonical URI for that request:

Link: <http://iiif.example.com/server/full/full/0/default.jpg>;rel="canonical"

The server may include this link header on the Image Information response, however it is unnecessary as it is included in the JSON representation retrieved.

5. Information Request

The Image Information document contains both metadata about the image, such as full height and width, and functionality available for it, such as the formats in which it may be retrieved. The service must return this information about the image. The request for the information must conform to the URI Template:

{scheme}://{server}{/prefix}/{identifier}/info.json

The syntax for the response is JSON-LD. The content-type of the response must be either “application/json” (regular JSON),

Content-Type: application/json

or “application/ld+json” (JSON-LD).

Content-Type: application/ld+json

If the client explicitly wants the JSON-LD content-type, then it must specify this in an Accept header, otherwise the server must return the regular JSON content-type.

If the regular JSON content-type is returned, then it is recommended that the server provide a link header to the context document. The syntax for the link header is below, and further described in section 6.8 of the JSON-LD specification. If the client requests “application/ld+json”, the link header may still be included but must be ignored. The entity body is identical regardless of the content-type, including the @context field.

Link: <http://iiif.io/api/image/2/context.json>
            ; rel="http://www.w3.org/ns/json-ld#context"
            ; type="application/ld+json"

Servers should send the Access-Control-Allow-Origin header with the value * in response to information requests. The syntax is shown below and is described in the CORS specification. This header is required in order to allow the JSON responses to be used by Web applications hosted on different servers.

Access-Control-Allow-Origin: *

A recipe for enabling these behaviors is provided in the Apache HTTP Server Implementation Notes.

5.1. Image Information

The JSON at the top level of the response will include the following properties:

The objects in the sizes list have the properties in the following table. Images requested using these sizes should have a region parameter of “full” and rotation of “0”. The full URL for an image with “default” quality in “jpg” format would be: {base_url}/{identifier}/full/{width},{height}/0/default.jpg

The objects in the tiles list have the properties in the following table. The width and height should be used to fill the region parameter and the scaleFactors to complete the size parameter of the image URL. This is described in detail in the Implementation Notes.

The width of a tile, or the combination of width and height if height is specified, must be unique among the members of the tiles list.

The objects in the profiles list have the properties in the following table. The @context, @id and @type properties are required when the profile is dereferenced from a URI, but should not be included in the Image Information response.

The set of features that may be specified in the supports property of an Image profile are:

The set of features, formats and qualities supported is the union of those declared in all of the external profile documents and any embedded profile objects. If a feature is not present in either the profile document or the supports property of an embedded profile, then a client must assume that the feature is not supported.

Servers should support requests for images with parameters specified by the sizes and tiles fields for all combinations of qualities and formats supported.

If any of formats, qualities, or supports have no additional values beyond those specified in the referenced compliance level, then the property should be omitted from the response rather than being present with an empty list.

URIs may be added to the supports list of a profile to cover features not defined in this specification. Clients must ignore URIs that are not recognized.

The JSON response is structured as shown in the following example. The order of the keys in the response should follow the order in the example.

{
  "@context" : "http://iiif.io/api/image/2/context.json",
  "@id" : "http://www.example.org/image-service/abcd1234/1E34750D-38DB-4825-A38A-B60A345E591C",
  "protocol" : "http://iiif.io/api/image",
  "width" : 6000,
  "height" : 4000,
  "sizes" : [
    {"width" : 150, "height" : 100},
    {"width" : 600, "height" : 400},
    {"width" : 3000, "height": 2000}
  ],
  "tiles": [
    {"width" : 512, "scaleFactors" : [1,2,4,8,16]}
  ],
  "profile" : [
    "http://iiif.io/api/image/2/level2.json",
    {
      "formats" : [ "gif", "pdf" ],
      "qualities" : [ "color", "gray" ],
      "supports" : [
          "canonicalLinkHeader", "rotationArbitrary", "profileLinkHeader", "http://example.com/feature/"
      ]
    }
  ],
  "service" : {
    "@context": "http://iiif.io/api/annex/service/physdim/1/context.json",
    "profile": "http://iiif.io/api/annex/service/physdim",
    "physicalScale": 0.0025,
    "physicalUnits": "in"
  }
}

Using the supplied JSON-LD frame will result in the correct structure.

6. Compliance Levels

The Image Information document must specify the extent to which the API is supported by including a compliance level URI as the first entry in the profile property. This URI links to a description of the highest compliance level for which all requirements are met. The URI must be one of those listed in the Image API Compliance document. This description contains the set of features required by the profile, as discussed in Image Information. A server may declare different compliance levels for images with different identifiers.

The compliance level URI may also be given in the HTTP Link header (RFC5988) with the parameter rel="profile", and thus a complete header might look like:

Link: <http://iiif.io/api/image/2/level1.json>;rel="profile"

A recipe for setting this header on the Apache HTTP Server is shown in the Apache HTTP Server Implementation Notes.

7. Server Responses

7.1. Successful Responses

Servers may transmit HTTP responses with 200 (Successful) or 3xx (Redirect) status codes when the request has been successfully processed. If the status code is 200, then the entity-body must be the requested image or information document. If the status code is 301, 302, 303, or 304, then the entity-body is unrestricted, but it is recommended to be empty. If the status code is 301, 302, or 303 then the Location HTTP Header must be set containing the URI of the image that fulfills the request. This enables servers to have a single canonical URI to promote caching of responses. Status code 304 is handled exactly as per the HTTP specification. Clients should expect to encounter all of these situations and must not assume that the entity-body of the initial response necessarily contains the image data.

7.2. Error Conditions

The order in which servers parse requests and detect errors is not specified. A request is likely to fail on the first error encountered and return an appropriate HTTP status code, with common codes given in the list below. It is recommended that the body of the error response includes a human-readable description of the error in either plain text or html.

8. Authentication

This API does not specify whether the image server will support authentication or what mechanism it might use. In the case of “401 Unauthorized” HTTP response, the content of the WWW-Authenticate header will depend on the authentication mechanism supported by the server. If the server supports HTTP Basic or Digest authentication then the header should follow RFC2617, for example:

WWW-Authenticate: Basic realm="Images"

9. URI Encoding and Decoding

The URI syntax of this API relies upon slash (/) separators which must not be encoded. Clients must percent-encode special characters (the to-encode set below: percent and gen-delims of RFC3986 except the colon) plus any characters outside the US-ASCII set within the components of requests. For example, any slashes within the identifier part of the URI must be percent-encoded. Encoding is necessary only for the identifier because other components will not include special characters. Percent-encoding other characters introduces no ambiguity but is unnecessary.

to-encode = "/" / "?" / "#" / "[" / "]" / "@" / "%"

Servers which are incapable of processing arbitrarily encoded identifiers should make their best efforts to expose only image identifiers for which clients will not encode any of the characters, and thus it is recommended to limit characters in identifiers to letters, numbers and the underscore character.

10. Security Considerations

This API defines a URI syntax and the semantics associated with its components. The composition of URIs has few security considerations except possible exposure of sensitive information in URIs or revealing of browse/view behavior of users.

Server applications implementing this API should consider possible denial-of-service attacks, and authentication vulnerabilities based on DNS spoofing. Applications must be careful to parse incoming requests (URIs) in ways that avoid overflow or injection attacks.

Early sanity checking of URIs (lengths, trailing GET, invalid characters, out-of-range parameters) and rejection with appropriate response codes is recommended.

11. Appendices

A. Implementation Notes

• For use cases that enable the saving of the image, it is recommended to use the HTTP Content-Disposition header (RFC6266) to provide a convenient filename that distinguishes the image, based on the identifier and parameters provided.
• This specification makes no assertion about the rights status of requested images or any other descriptive metadata, whether or not authentication has been accomplished. Please see the IIIF Presentation API for rights and other information.
• Additional Apache HTTP Server implementation notes are available.
• When requesting sizes using the w, canonical syntax, if a particular height is desired, the following algorithm can be used:

    # Calculate request width for `w,` syntax from desired height
    request_width = image_width * desired_height / image_height

• When requesting image tiles, the Region and Size parameters must be calculated to take account of partial tiles along the right and lower edges for a full imagine that is not an exact multiple of the scaled tile size. The algorithm below is shown as Python code and assumes integer inputs and integer arithmetic throughout (ie. remainder discarded on division). Inputs are: size of full image content (width,height), scale factor s, tile size (tw,th), and tile coordinate (n,m) counting from (0,0) in the upper-left corner. Note that the rounding method is implementation dependent.

    # Calculate region parameters /xr,yr,wr,hr/
    xr = n * tw * s
    yr = m * th * s
    wr = tw * s
    if (xr + wr > width):
        wr = width - xr
    hr = th * s
    if (yr + hr > height):
        hr = height - yr
    # Calculate size parameters /ws,hs/
    ws = tw
    if (xr + tw*s > width):
        ws = (width - xr + s - 1) / s  # +s-1 in numerator to round up
    hs = th
    if (yr + th*s > height):
        hs = (height - yr + s - 1) / s

• As described in Rotation, in order to retain the size of the requested image contents, rotation will change the width and height dimensions of the image returned. A formula for calculating the dimensions of the image returned for a given starting size and rotation is given below. Note that the rounding method is implementation dependent and that some languages require conversion of the angle from degrees to radians.

    # (w,h) are size parameters, n is rotation angle
    w_returned = abs(w*cos(n)) + abs(h*sin(n))
    h_returned = abs(h*cos(n)) + abs(w*sin(n))

B. Versioning

Starting with version 2.0, this specification follows Semantic Versioning. See the note Versioning of APIs for details regarding how this is implemented.

C. Acknowledgments

The production of this document was generously supported by a grant from the Andrew W. Mellon Foundation.

Many thanks to Ben Albritton, Matthieu Bonicel, Anatol Broder, Kevin Clarke, Tom Cramer, Ian Davis, Neil Jefferies, Scotty Logan, Sean Martin, Roger Mathisen, Lynn McRae, Willy Mene, Mark Patton, Petter Rønningsen, and Brian Tingle for your thoughtful contributions to the effort and written feedback. Thanks also to the members of the IIIF Community for their continuous engagement, innovative ideas and feedback.

D. Change Log