Image API 3.0

Status of this Document

This Version: 3.0.0

Latest Stable Version: 3.0.0

Previous Version: 2.1.1

Editors:

• Michael Appleby, Yale University

• Tom Crane, Digirati

• Robert Sanderson, J. Paul Getty Trust

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

1. Introduction

This document describes an image delivery API defined by the International Image Interoperability Framework (IIIF, pronounced “Triple-Eye-Eff”) Consortium. 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.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 requests that follow 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.

Implementations may use a pre-generated set of files served as static web resources and still enable rich user experiences. Dynamic image server implementations may provide additional functionality beyond the base level of compliance.

1.2. Terminology

The term underlying image content is used to refer to the source image data. No assumptions are made about its format or structure. It might be derived from one or more source images but could also be dynamically generated.

The term full image is used to refer to the entire area of the underlying image content, with the pixel dimensions given in the image information document, and which is imagined as the starting point for image requests.

The key words must, must not, required, shall, shall not, should, should not, recommended, and optional in this document are to be interpreted as described in RFC 2119.

2. URI Syntax

The IIIF Image API can be called in two ways:

• Request an image, derived from the underlying image content.
• Request information about the image service, including characteristics, functionality available, and related services.

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 service’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:

https://example.org/image-service/abcd1234/full/max/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 Requests.

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:

https://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 Requests

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 full image, then scaled to the requested size, mirrored and/or rotated, and finally transformed into the requested color quality and format. This resulting image is returned as the representation for the URI.

Size and region parameters in pixels must be non-negative integers. Size and region parameters in percentages and the rotation parameter must be positive floating point numbers or integers. For details of the representation of floating point numbers in IIIF URIs, see the Floating Point Values section.

Servers should support CORS on image responses.

4.1. Region

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

If the request specifies a region which extends beyond the dimensions of the full image as 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 (Bad Request) status code.

Examples:

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

4.2. Size

The size parameter specifies the dimensions to which the extracted region, which might be the full image, is to be scaled. With the exception of the w,h and ^w,h forms, the returned image maintains the aspect ratio of the extracted region as closely as possible. Sizes prefixed with ^ allow upscaling of the extracted region when its pixel dimensions are less than the pixel dimensions of the scaled region.

Requests for sizes not prefixed with ^ that result in a scaled region with pixel dimensions greater than the pixel dimensions of the extracted region are errors that should result in a 400 (Bad Request) status code.

Requests for sizes prefixed with ^ that require upscaling should result in a 501 (Not Implemented) status code if the server does not support upscaling, while a 400 (Bad Request) status code should be returned in response to other client request syntax errors. For example, a request for the size ^pct:120 should result in a 501 status code if the server does not support upscaling.

For all requests the pixel dimensions of the scaled region must not be less than 1 pixel or greater than the server-imposed limits. Requests that would generate images of these sizes are errors that should result in a 400 (Bad Request) status code.

Examples:

1 size=max .../full/max/0/default.jpg N.B. Assuming that the image has a maxWidth of 200px	1 size=^max .../full/^max/0/default.jpg N.B. Assuming that the image has a maxWidth of 360px
2 size=150, .../full/150,/0/default.jpg	2 size=^360, .../full/^360,/0/default.jpg
3 size=,150 .../full/,150/0/default.jpg	3 size=,^240 .../full/,^240/0/default.jpg
4 size=pct:50 .../full/pct:50/0/default.jpg	4 size=pct:120 .../full/pct:120/0/default.jpg
5 size=225,100 .../full/225,100/0/default.jpg	5 size=^360,360 .../full/^360,360/0/default.jpg
6 size=!225,100 .../full/!225,100/0/default.jpg N.B. Returned image is 150,100 px	6 size=^!360,360 .../full/^!360,360/0/default.jpg N.B. Returned image is 360,240 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 (Bad Request) status code.

In most cases, 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.

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/max/0/default.jpg	2 rotation=180 .../full/max/180/default.jpg
3 rotation=90 .../full/max/90/default.jpg	4 rotation=22.5 .../full/max/22.5/default.png
5 rotation=!0 .../full/max/!0/default.jpg	6 rotation=!180 .../full/max/!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,80/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.

Regardless of level of compliance, services that make additional qualities beyond default available must list those qualities in the extraQualities property of the response to the Image Information Request. A request for an image with an unsupported quality value should return a 400 (Bad Request) status code.

A request for the color quality of an image must return an image. This image may be comprised solely of grayscale or bitonal pixels if this is all of the color information the server has available. The server should not include color in the extraQualities list in such cases, but a request for the color quality must not result in an error. Similarly, a request for the grayscale quality may return an image comprised solely of bitonal pixels.

Examples:

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

4.5. Format

The format of the returned image is expressed as a suffix, mirroring common filename extensions, at the end of the URI.

A format value that is unsupported should result in a 400 (Bad Request) status code.

Examples:

1. .../full/max/0/default.jpg
2. .../full/max/0/default.png
3. .../full/max/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 underlying image content. This is important to consider when implementing the image service because applying the same parameters in a different sequence will often result in a different image being delivered.

The parameters should be interpreted as if 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. Floating Point Values

Size and region parameters given as percentages and the rotation parameter allow positive floating point number values. Integer values should be used where possible. When floating point values are used, they must consist only of decimal digits and “.” (e.g. 0.9 not +0.9), should be represented with a leading 0 if less than 1 (e.g. 0.9 not .9), and should not include trailing zeros (e.g. 0.9 not 0.90). Intermediate calculations may use floating point numbers and the rounding method is implementation specific.

4.8. Canonical URI Syntax

It is possible to request the same image using different combinations of 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 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/400,300/0/default.jpg>;rel="canonical"

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

4.9. Extensions

The IIIF Image API is extensible within the Image Request URI Syntax through the addition of new parameter patterns for the region, size and rotation parameters, or new values for the quality and format parameters. Request information beyond the scope of the existing parameters could be passed to an image server as query parameters. Extension features should be described in the image information document following the guidelines in the Extra Functionality section.

5. Image Information

Servers must support requests for image information. The response is a JSON document that includes technical properties about the full image. It may also contain rights information, and services related to the image.

5.1. Image Information Request

The request for the image information must conform to the URI template:

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

The syntax for the response is JSON-LD. If the server receives a request with an Accept header, it should respond following the rules of content negotiation. Note that content types provided in the Accept header of the request may include parameters, for example profile or charset.

If the request does not include an Accept header, the HTTP Content-Type header of the response should have the value application/ld+json (JSON-LD) with the profile parameter given as the context document: http://iiif.io/api/image/3/context.json.

Content-Type: application/ld+json;profile="http://iiif.io/api/image/3/context.json"

If the Content-Type header application/ld+json cannot be generated due to server configuration details, then the Content-Type header should instead be application/json (regular JSON), without a profile parameter.

Content-Type: application/json

Servers should support CORS on image information responses.

5.2. Technical Properties

The JSON response has several technical properties that describe the available functionality for the image content.

The width and height properties give the size of the full image and are required in order to construct tile requests.

The maxWidth, maxHeight, and maxArea parameters provide a way for image servers to express limits on the sizes supported for the image. If maxWidth alone, or maxWidth and maxHeight are specified then clients should expect requests with larger linear dimensions to be rejected. If maxArea is specified then clients should expect requests with larger pixel areas to be rejected. The maxWidth / maxHeight and maxArea parameters are independent, servers may implement either or both limits. Servers must ensure that sizes specified by any sizes or tiles properties are within any size limits expressed. Clients should not make requests that exceed size limits expressed.

{
  "@context": "http://iiif.io/api/image/3/context.json",
  "id": "https://example.org/image-service/abcd1234/1E34750D-38DB-4825-A38A-B60A345E591C",
  "type": "ImageService3",
  "protocol": "http://iiif.io/api/image",
  "profile": "level2",
  "width": 6000,
  "height": 4000,
  "maxHeight": 2000,
  "maxWidth": 3000,
  "maxArea": 4000000
}

5.3. Sizes

The JSON response may have the sizes property, which is used to describe preferred height and width combinations for representations of the full image.

The JSON objects in the sizes array have the properties in the following table. Image requests for these sizes should have a region parameter of full, size parameter in the canonical w,h form, and rotation of 0. Thus, the full URL for an image with default quality in jpg format would be: {scheme}://{server}/{prefix}/{identifier}/full/{width},{height}/0/default.jpg

{
  "@context": "http://iiif.io/api/image/3/context.json",
  "id": "https://example.org/image-service/abcd1234/1E34750D-38DB-4825-A38A-B60A345E591C",
  "type": "ImageService3",
  "protocol": "http://iiif.io/api/image",
  "profile": "level2",
  "width": 6000,
  "height": 4000,
  "sizes": [
    { "width": 150, "height": 100 },
    { "width": 600, "height": 400 },
    { "width": 3000, "height": 2000 }
  ]
}

5.4. Tiles

The JSON response may have the tiles property which describes a set of image regions that have a consistent height and width, over a series of resolutions, that can be stitched together visually.

The JSON objects in the tiles array have the properties in the following table. The width and height should be used to fill the size parameter, and be used together with the scaleFactors to compute the region parameter of the image requests. This is described in detail in the Implementation Notes.

Objects in the tiles array must each have a unique combination of width and height, where height = width if it is not explicitly specified.

{
  "@context": "http://iiif.io/api/image/3/context.json",
  "id": "https://example.org/image-service/abcd1234/1E34750D-38DB-4825-A38A-B60A345E591C",
  "type": "ImageService3",
  "protocol": "http://iiif.io/api/image",
  "profile": "level2",
  "width": 6000,
  "height": 4000,
  "tiles": [
    { "width": 512, "scaleFactors": [ 1, 2, 4, 8, 16 ] }
  ]
}

5.5. Preferred Formats

The JSON response may have the preferredFormats property, which lists one or more format parameter values for this image service. This allows the publisher to express a preference for the format a client requests, for example to encourage use of a more efficient format such as webp, or to suggest a format that will give better results for the image content, such as lossless webp or png for line art or graphics.

{
  "@context": "http://iiif.io/api/image/3/context.json",
  "id": "https://example.org/image-service/",
  "type": "ImageService3",
  "protocol": "http://iiif.io/api/image",
  "profile": "level2",
  "width": 6000,
  "height": 4000,
  "extraFormats": [ "webp" ],
  "preferredFormats": [ "webp", "png" ]
}

5.6. Rights

The rights property has the same semantics and requirements as it does in the Presentation API.

If the publisher of this image requires additional information to be shown when it is viewed, the information should be provided by a Presentation API Manifest, as described in the Linking Properties section.

{
  "@context": "http://iiif.io/api/image/3/context.json",
  "id": "https://example.org/image-service/abcd1234/1E34750D-38DB-4825-A38A-B60A345E591C",
  "type": "ImageService3",
  "protocol": "http://iiif.io/api/image",
  "profile": "level2",
  "width": 6000,
  "height": 4000,
  "rights": "http://rightsstatements.org/vocab/InC-EDU/1.0/"
}

5.7. Extra Functionality

The JSON response may also contain properties that describe additional functionality available via the image service.

The following features are defined for use in the extraFeatures property:

A server that supports neither sizeByW or sizeByWh is only required to serve the image sizes listed under the sizes property or implied by the tiles property of the image information document, allowing for a static file implementation.

A server that supports sizeUpscaling must specify maxWidth or maxArea (see Technical Properties).

The set of features, formats and qualities supported is the union of those declared in the external profile document and those added by the extraQualities, extraFormats, and extraFeatures properties. If a feature is not present in either the profile document or the extraFeatures property, then a client must assume that the feature is not supported.

Additional strings used in the extraQualities, extraFormats, and extraFeatures properties, or additional properties used in the image information, that are not defined in this specification should be mapped to RDF predicates using further context documents. These extensions should be added to the top level @context property (see Technical Properties). The JSON-LD 1.1 functionality of predicate specific context definitions, known as scoped contexts, must be used to minimize cross-extension collisions. Extensions intended for community use should be registered in the extensions registry, but registration is not mandatory.

{
  "@context": "http://iiif.io/api/image/3/context.json",
  "id": "https://example.org/image-service/abcd1234/1E34750D-38DB-4825-A38A-B60A345E591C",
  "type": "ImageService3",
  "protocol": "http://iiif.io/api/image",
  "profile": "level2",
  "width": 6000,
  "height": 4000,
  "extraFormats": [ "gif", "pdf" ],
  "extraQualities": [ "color", "gray" ],
  "extraFeatures": [ "canonicalLinkHeader", "rotationArbitrary", "profileLinkHeader" ]
}

5.8. Linking Properties

The JSON response may contain linking properties that reference external resources, including services that make additional functionality available to a viewer. The linking properties have the same semantics and requirements as those in the Presentation API.

The JSON objects in partOf, seeAlso, and service have the properties indicated in the following table.

{
  "@context": [
    "http://iiif.io/api/image/3/context.json"
  ],
  "id": "https://example.org/image-service/abcd12345/1E34750D-38DB-4825-A38A-B60A345E591C",
  "type": "ImageService3",
  "protocol": "http://iiif.io/api/image",
  "profile": "level2",
  "width": 6000,
  "height": 4000,
  "seeAlso": [
    {
      "id": "https://example.org/image1.xml",
      "label": { "en": [ "Technical image metadata" ] },
      "type": "Dataset",
      "format": "text/xml",
      "profile": "https://example.org/profiles/imagedata"
    }
  ],
  "partOf": [
    {
      "id": "https://example.org/manifest/1",
      "type": "Manifest",
      "label": { "en": [ "A Book" ] }
    }
  ],
  "service": [
    {
      "@id": "https://example.org/auth/login",
      "@type": "AuthCookieService1",
      "profile": "http://iiif.io/api/auth/1/login",
      "label": "Login to Example Institution"
    }
  ]
}

5.9. Complete Response

The following shows an image information response including all of the required and optional properties.

{
  "@context": [
    "http://example.org/extension/context1.json",
    "http://iiif.io/api/image/3/context.json"
  ],
  "id": "https://example.org/image-service/abcd1234/1E34750D-38DB-4825-A38A-B60A345E591C",
  "type": "ImageService3",
  "protocol": "http://iiif.io/api/image",
  "profile": "level1",
  "width": 6000,
  "height": 4000,
  "maxWidth": 3000,
  "maxHeight": 2000,
  "maxArea": 4000000,
  "sizes": [
    { "width": 150, "height": 100 },
    { "width": 600, "height": 400 },
    { "width": 3000, "height": 2000 }
  ],
  "tiles": [
    { "width": 512, "scaleFactors": [ 1, 2, 4 ] },
    { "width": 1024, "height": 2048, "scaleFactors": [ 8, 16 ] }
  ],
  "rights": "http://rightsstatements.org/vocab/InC-EDU/1.0/",
  "preferredFormats": [ "png", "gif"],
  "extraFormats": [ "png", "gif", "pdf" ],
  "extraQualities": [ "color", "gray" ],
  "extraFeatures": [ "canonicalLinkHeader", "rotationArbitrary", "profileLinkHeader" ],
  "service": [
    {
      "id": "https://example.org/service/example",
      "type": "Service",
      "profile": "https://example.org/docs/example-service.html"
    }
  ]
}

6. Compliance Level and Profile Document

The image information document must specify the extent to which the API is supported by including the compliance level as the value of the profile property. The compliance level must be one of those listed in the Image API Compliance document and shown in the table below. The compliance level should be the highest compliance level for which all requirements are met. The compliance levels each correspond with a profile document that describes the set of features required by that level, as discussed in the Image Information section. A server may declare different compliance levels for images with different identifiers.

The compliance level may also be given in a HTTP Link header (RFC5988), using the profile document URI with the parameter rel="profile", on both Image and Image Information responses. A complete header might look like:

Link: <http://iiif.io/api/image/3/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

Servers must support the HTTP GET method for retrieval of Image API resources. Servers should support the HTTP OPTIONS method as part of the CORS preflight request pattern, and it is recommended that implementations also support the HTTP HEAD method.

7.1. CORS

Servers should support reuse of Image API resources by following the relevant requirements of the CORS specification, including the Access-Control-Allow-Origin header and the preflight request pattern. A recipe for enabling these behaviors is provided in the Apache HTTP Server Implementation Notes.

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

7.4. HTTP Versions

Implementations that anticipate the need to respond to many concurrent requests from the same client should make the API available via HTTP/2 in order to avoid repeatedly opening and closing connections. This also avoids the browser-imposed limit on the number of concurrent connections per site via HTTP 1.1.

8. Authentication

Images are generally secondary resources in a web page or application. In the case of web pages, images are embedded in the HTML img tag, and are retrieved via additional HTTP requests. When a user cannot load a web page, it is possible — and a generally accepted behavior — to redirect the user to another page and offer the opportunity to authenticate. This is not an option for secondary resources such as images, and the user is instead simply presented with a broken image icon.

No new authentication mechanisms are proposed, nor roles for authorization business logic. Instead, it is expected that authentication requirements and processes are handled outside of any IIIF-specific context, but within a IIIF-aware access control workflow. Please see the IIIF Authentication specification.

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 and sanitize incoming requests (URIs) in ways that avoid overflow, injection, and directory traversal 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. Versioning

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

B. Acknowledgments

Many thanks to the members of the IIIF community for their continuous engagement, innovative ideas and feedback.

C. Change Log