Getting more out of IO with image transformation classes

Senior Manager, Product Management, Fastly

September 26, 2017

Since we announced the Fastly Image Optimizer as part of our edge cloud platform, we’ve seen many of our customers adopt Fastly IO, taking advantage of its ability to transform and generate unique image variations at scale, in real time, via a simple and configurable URL-based API. (We encourage you to try it out if you haven’t already.)

We’ve worked to ensure Fastly IO is simple, easy to use, and most importantly, fully integrated into the platform. In an effort to give you even more control, we've developed image transformation classes to help streamline, secure, and support your image delivery workflow.

What is an image transformation class?

An image transformation class describes the mapping of IO query string API parameters to a configurable key-value pair inside a lookup table. This layer of abstraction allows for precise control over what reaches the image transformation servers and how the Fastly IO API is visually presented in a codebase.

The following image URL demonstrates a transformation class in action:
https://www.fastly.io/transformation-class/image.jpg?class=large

The query string parameter class=large is used to deliver an image cropped to an aspect ratio of 16:9, resized to a width of 640px, and 75% quality compression, as shown below.

![io image](https://www.fastly.io/transformation-class/image.jpg?class=large)

Without image transformation classes, the IO API would require multiple parameters (crop, width, and quality) to be specified in order to deliver the same image output:

https://www.fastly.io/transformation-class/image.jpg?crop=16:9&width=640&quality=75

Advantages of image transformation classes

Image transformation classes will simplify your workflows by helping maintain existing image URLs for legacy or SEO reasons, streamline image delivery across all your internet properties, and help maximize cache hit ratio.

1. Support existing image URL patterns

Having the ability to define an API around your existing image delivery workflow makes implementing IO to a production environment faster and more familiar. Image transformation classes can be used to support existing image URL patterns without changing a production codebase, removing the need for any engineering effort and enabling your engineers to focus on building other products.

2. Keep changes in sync

As changes to the IO classes are made in one central place (the lookup table), your transformation logic is defined once. This is useful when redesigning your front-end interface, as any changes made to the design that affect the existing image classes (new image sizes, different output formats, etc.) are synchronized across all your websites and native apps that adopt the classes.

3. Only expose the features you need

You can use image transformation classes to restrict or lock down access to the IO API, which is particularly useful when only a subset of functionality is required, or if you don’t want your users to have the ability to generate new and unique images by changing query string values (which can have a negative effect on cache hit ratio).

How to implement image transformation classes

Although any number of items can be stored in the lookup table, the following examples demonstrate three possible classes: large, medium, and small.

We also need to address a few edge cases:

Class is not specified or doesn't exist

If a class does not match large, medium, or small — or the class is not present — we can opt to use a default class rather than delivering the original larger image. The following two URLs deliver a default transformation due to the class not matching or being present:

https://www.fastly.io/transformation-class/example-1/image.jpg?class=large (works)
https://www.fastly.io/transformation-class/example-1/image.jpg?class=foo (uses default)
https://www.fastly.io/transformation-class/example-1/image.jpg (uses default)

Alternatively, you could choose to return a 404 not found error:

Note: It’s also possible to customize your 404 page — check out our documentation on how to create error pages with custom responses.

Native IO params mixed with classes

You might also want to tweak an image transformation class for a particular use case, such as using IO on a microsite for a short-lived campaign (for which adding additional permanent rules might not be necessary).

The following image URL demonstrates how classes can be overridden with IO query string parameters specified inline. In this example, we’re overriding the predefined width set in the lookup table from 100px to 200px:

https://www.fastly.io/transformation-class/example-3/image.jpg?class=small&width=200

Of course, allowing this kind of override will also allow end users to gain access to original-resolution images by setting very large values for the width and height properties, so you may only want to allow IO params in some cases, or only some params.

The code!

Check out this example, which combines all the options above to create three named classes, large, medium and small, allow a default to be specified, and support stripping IO params from the input if you don't want to allow overrides.

Learn more about Fastly IO’s edge transformations

For more information on image transformation classes and other edge transformations, watch our Altitude NYC workshop video, where Director of Engineering Ines Sombra, Senior Architect Ed Thurgood, and Herman Radtke, VP of Engineering at Nordstromrack.com | Hautelook, talk about the many advantages of implementing image optimization at the edge.