Image Service REST API

Streaming Image Service

This document describes the REST API for the Stanford Digital Stacks Image Service. The base image service URL is 'http://stacks.stanford.edu/image/<druid>/<filename>' which will render the most appropriate image based on the default behavior defined below.

Public Image Streaming Service

The public image streaming service builds upon the base image service URL to generate different renderings of an image. Below are examples of how to generate precast sizes renderings of an image, different image output formats, image transformations using rotation, and to allow downloading of an image:

Size Categories (defaults to largest publicly available size which is currently hardcoded to 'large')
See Djatoka Level Logic on how the maximum Djatoka level is defined Size Category Square Thumbnail Small Medium Large XLarge Full Image Service URL http://stacks.stanford.edu/image/<druid>/<filename>_square http://stacks.stanford.edu/image/<druid>/<filename>_thumb http://stacks.stanford.edu/image/<druid>/<filename>_small http://stacks.stanford.edu/image/<druid>/<filename>_medium http://stacks.stanford.edu/image/<druid>/<filename>_large http://stacks.stanford.edu/image/<druid>/<filename>_xlarge http://stacks.stanford.edu/image/<druid>/<filename>_full Equivalent Djatoka Level n/a n/a <max-level> - 4 <max-level> - 3 <max-level> - 2 <max-level> - 1 <max-level> Percentage of Full-Size Image n/a n/a 6.25% 12.5% 25% 50% 100%

If an unknown value for size is requested, we will respond with an HTTP 400 error, with links to the xml and json lists of available sizes

Image Formats (defaults to jpg - implicit default used by djatoka)

Image Format jpg png gif bmp Image Service URL http://stacks.stanford.edu/image/<druid>/<filename>.jpg http://stacks.stanford.edu/image/<druid>/<filename>.png http://stacks.stanford.edu/image/<druid>/<filename>.gif http://stacks.stanford.edu/image/<druid>/<filename>.bmp

Transformations (defaults to 0 - implicit default used by djatoka)

Transformation Rotate 90 Rotate 180 Rotate 270 Image Service URL http://stacks.stanford.edu/image/<druid>/<filename>?rotate=90 http://stacks.stanford.edu/image/<druid>/<filename>?rotate=180 http://stacks.stanford.edu/image/<druid>/<filename>?rotate=270

Actions (defaults to streaming an image - implicit default used by djatoka)

Action Download Rendered Version Image Service URL http://stacks.stanford.edu/image/<druid>/<filename>?action=download Questions

Download Original Version

http://stacks.stanford.edu/file/<druid>/<filename>

Should the original source image be downloadable?

List of available sizes and formats

You can obtain a list of available sizes for a given image, in xml or json format Format xml json Image Service URL http://stacks.stanford.edu/image/<druid>/<filename>.xml http://stacks.stanford.edu/image/<druid>/<filename>.json

Below are several examples of how the optional public parameters can be used in combination: Description Streamed thumbnail-sized png image Streamed medium-sized gif image rotated 180 Downloadable full-sized jpg image rotated 90 Downloadable largest-sized png image rotated 270 Image Service URL http://stacks.stanford.edu/image/<druid>/<filename>_thumb.png http://stacks.stanford.edu/image/<druid>/<filename>_medium.gif?rotate=180 http://stacks.stanford.edu/image/<druid>/<filename>_full?action=download&rotate=90 http://stacks.stanford.edu/image/<druid>/<filename>.png?action=download&rotate=270

Privileged Image Streaming Service

The privileged image streaming service has all the capabilities of the public image streaming service as well as the following additional services:

Zoom Level
Percentage Zoom 36 Image Service URL http://stacks.stanford.edu/image/<druid>/<filename>?zoom=36

Zoom is a percentage of the full-size image

Region of Interest
Region (x,y,w,h) 300 x 500 Region Starting at (50,100) within the 6.25% zoom level Image Service URL http://stacks.stanford.edu/image/<druid>/<filename>?zoom=6.25&region=50,100,300,500

Region is relative to the zoom level or pre-cast image size requested. If passing zoom level, it must be equivalent to an existing Djatoka level (50, 25, 12.5, etc.) All 4 values must be supplied

Scaling of the Output

Dimensions Absolute Dimensions of 600 x 800 pixels Long Edge Width Dimension of 600 pixels Long Edge Height Dimension of 800 pixels Image Service URL http://stacks.stanford.edu/image/<druid>/<filename>?w=600&h=800 http://stacks.stanford.edu/image/<druid>/<filename>?w=600 http://stacks.stanford.edu/image/<druid>/<filename>?h=800

If sent without region, this is relative to the full size image

Below are several examples of how the public and privileged parameters can be used in combination. (Note: The exception to this rule is when a size category AND any privileged parameter are specified in combination. Size categories cannot be used in combination with privileged parameters and results in an error. This is because the image service does not determine whether public or privileged parameters take precedence over each other). Description Streamed png image scaled to 600 x 800 Downloadable gif image scaled to a 600-pixel width Downloadable jpg image with a region of 300 x 500 starting at (0,0) Downloadable gif image with a region of 300 x 500 starting at (50,100) rotated 180 Image Service URL http://stacks.stanford.edu/image/<druid>/<filename>.png?w=600&h=800

http://stacks.stanford.edu/image/<druid>/<filename>.gif?w=600&action=download

http://stacks.stanford.edu/image/<druid>/<filename>?action=download&region=300,500

http://stacks.stanford.edu/image/<druid>/<filename>.gif?action=download&region=50,100,300,500&rotate=180

Depreciated operations
Predefined Resolution Level Replaced by Zoom Level
Resolution Level Resolution at Minimum Level Resolution at Level 1 Resolution at Level 2 Resolution at Level 3 Resolution at Maximum Level Image Service URL http://stacks.stanford.edu/image/<druid>/<filename>?level=0 http://stacks.stanford.edu/image/<druid>/<filename>?level=1 http://stacks.stanford.edu/image/<druid>/<filename>?level=2 http://stacks.stanford.edu/image/<druid>/<filename>?level=3 http://stacks.stanford.edu/image/<druid>/<filename>?level=<max_level>