imclab / image-service

Image resizing proxy for FT responsive images

Responsive images service

Image resizing proxy for FT responsive images.

Placeholder repo to speculatively define the service that we might build. This service doesn't actually work

API reference

API endpoints as follows:

GET /v1/images/:mode/:uri,:uri,…
GET /v1/images/:mode?imageset=:imageset

Fetch an image or set of images, format and serve them.

Param	Where	Description
mode	URL	How output should be packaged. raw Output raw image data. Requests for multiple images must will be output as a sprite in which the images are tiled in a single horizontal line. Per-image `format` override not available for this output mode (because you can't output an image that is part PNG, part JPEG!) css-sprite Output a CSS spritesheet containing the images as data URIs attached to classes with names matching the input identifiers (as closely as possible) data Output a JSON array of data URIs data-utfhack Output a JSON array of data URIs, in which each character of the base64 is a UTF character hiding two ASCII characters
uri	URL, imageset	An URL-encoded URI to use as the image source, e.g. /v1/images/raw/flags%3Agb,http%3A%2F%2Fexample.com%2Fimage%2Ejpg. Scheme part of the URI may be omitted if the source property is provided. Alternative to the imageset property.
source	Querystring	Default type of source/scheme in uris. Custom schemes allow the service to back onto a variety of data sources, including sets of images that may be built into the service itself. Supported source types: http HTTP URLs of source images anywhere on the public web https HTTPS URLs of source images anywhere on the public web flags ISO 3166 two letter country codes heads Slugified names of known FT columnists and others for whom we show headshots icons Identifiers for icons within standard FT icon set social Identifiers for button images representing common social platforms (e.g. facebook, twitter, linkedin, reddit, tumblr, digg, weibo, douban, googleplus) ftcms UUID of image in Content API *(Problem: can't currently look up an image)*
imageset	Querystring	A JSON array of objects in which each object has a required uri property along with (optionally) other imageset-compatible properties defined on this API. Any property not defined for an individual image will fall back to the value defined for the request (and then to the default, if not defined on the query string). The uri property may include URI without a scheme if source property is provided.
width	Querystring, imageset	Width of desired output image in pixels. Defaults to a width that maintains the aspect of the image, or the width of the source image if `height` is also not set.
height	Querystring, imageset	Height of desired output image in pixels. Defaults to a height that maintains the aspect of the image, or the height of the source image if `width` is also not set.
fit	Querystring, imageset	Type of transform to apply if the source aspect ratio does not perfectly match the target (subset of rules defined by CSS `object-fit` property): cover (default) The image should be scaled to be as small as possible while ensuring both its dimensions are greater than or equal to the corresponding dimensions of the frame, and any cropping should be taken equally from both ends of the overflowing dimension contain The image should be scaled to be as large as possible while ensuring both its dimensions are less than or equal to the corresponding dimensions of the frame. The frame should then be collapsed to match the aspect ratio of the image. contain-padded The image should be scaled to be as large as possible while ensuring both its dimensions are less than or equal to the corresponding dimensions of the frame. Any space in the frame not occupied by the image should be transparent or filled with `bgcolor`. fill The image should be scaled so that both its dimensions exactly match the frame, regardless of its original aspect ratio.
bgcolor	Querystring, imageset	Background colour to apply to regions of images that would be transparent where the output image format does not support transparency (ie, JPEG). Specified as six-character RGB hex code, eg `00ff00`
format	Querystring, imageset	Desired output format. auto (default) Use Accept header from request to determine the best output format jpg Format images as jpg png Format images as png webp Format images as webp svg Format images as SVG (only available if source image is SVG)
quality	Querystring, imageset	Compression level for lossy encoding. May be set to 'lowest', 'low', 'medium', 'high', 'highest', or 'lossless'. If lossless is not supported by chosen image format (JPG), the highest level will be used instead. Default is medium.

The service stores cached copies of images as retrieved from origin. Cached copies of transformed images are cached by CDN.

Examples

Fetch flags of European countries at 40x30px as a CSS sprite

/v1/images/css-sprite/gb,fr,de,be,es,fi,hu,it,je,lt,no,pl,se?format=png&width=40&height=30&source=flags

Get a headshot of John Gapper at 50px wide in auto-detected image format:

/v1/images/raw/heads:john.gapper?width=50

Download a set of images for the web app based on their UUIDs, ready-encoded using UTF-hack:

/v1/images/data-utfhack?source=ftcms&imageset=[{"uri":"48c9d290-874b-11e3-baa7-0800200c9a66"},{"uri":"48c9d291-874b-11e3-baa7-0800200c9a66"}]&format=jpg

Download two flags, John Gapper's headshot, and an FTCMS image, all as data URIs in JSON array in one request

/v1/images/data?fit=cover&source=flags&imageset=[{"uri":"gb"},{"uri":"fr"},{"uri":"heads:john.gapper","width":50,"height":50},{"uri":"ftcms:48c9d290-874b-11e3-baa7-0800200c9a66"}]

Restricting use to FT sites

Image requests must contain a Referer header with a recognised FT site hostname.

Unresolved questions

• Art direction!
• Invocation in markup