You appear to be offline. Some site functionality may not work.
Sign Up

Fastly Blog

Getting more out of IO with image transformation classes

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

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.

Example 1: Image transformation class or a default fallback

If a class does not match large, medium, or small — or the class is not present — an image with a default width of 640px is delivered rather than the original larger dimensions:

The following two URLs deliver the fallback image due to the class not matching or being present:

To implement image transformation classes, or a default fallback in your own Fastly IO enabled service, use the following Custom VCL:

table io_classes {
   "large": "crop=16:9&width=640",
   "medium": "crop=4:3&width=320",
   "small": "crop=1:1&width=100"
}

sub vcl_recv {
 #FASTLY recv

 if (req.request != "HEAD" && req.request != "GET" && req.request != "FASTLYPURGE") {
   return(pass);
 }
 
 # Send urls with image extensions to Fastly IO
 if (req.url.ext ~ "(?i)^(gif|png|jpe?g|webp)$") {

   # Set the Fastly Image Optimizer header
   set req.http.X-Fastly-Imageopto-Api = "fastly";
   
   #Run Class Logic
   declare local var.pol STRING;
   if (req.url.qs ~ "(?:^|&)class=([^&]+)") {
     set var.pol = re.group.1;
   }
   set req.url = req.url.path "?" table.lookup(io_policies, var.pol, "width=640") "&class=" var.pol;
 }
 
 return (lookup);
}

Example 2: Image transformation class or 404

You may need your origin image to be protected from delivery due to licensing reasons. If a class does not match large, medium, or small — or the class is not present — the origin image can be prevented from being delivered by returning a HTTP 404 Not Found error instead:

In the following example, the URL includes the medium transformation class, so the appropriate image is delivered:

To implement image transformation classes, and protect your origin image from delivery in your own IO enabled service, use the following Custom VCL:

table io_classes {
    "large": "crop=16:9&width=640",
    "medium": "crop=4:3&width=320",
    "small": "crop=1:1&width=100"
}

sub vcl_recv {
  #FASTLY recv

  if (req.request != "HEAD" && req.request != "GET" && req.request != "FASTLYPURGE") {
    return(pass);
  }
  
  # Send urls with image extensions to Fastly IO
  if (req.url.ext ~ "(?i)^(gif|png|jpe?g|webp)$") {

    # Set the Fastly Image Optimizer header
    set req.http.X-Fastly-Imageopto-Api = "fastly";

    # Run Class Logic    
    declare local var.pol STRING;
    set var.pol = table.lookup(
        io_classes,
        if(req.url.qs ~ "(?:^|&)class=([^&]+)", re.group.1, ""),
        "");
    if (var.pol == "") {
        error 404;
    }
    set req.url = req.url.path "?" var.pol "&class=" re.group.1;
  }

  return (lookup);
}

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

Example 3: Extending image transformation classes with IO query string parameters

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:

To extend image transformation classes in your own IO enabled service, use the following Custom VCL:


table io_classes {
    "large": "crop=16:9&width=640",
    "medium": "crop=4:3&width=320",
    "small": "crop=1:1&width=100"
}

sub vcl_recv {
#FASTLY recv
  if (req.request != "HEAD" && req.request != "GET" && req.request != "FASTLYPURGE") {
    return(pass);
  }
  
  # Send urls with image extensions to Fastly IO
  if (req.url.ext ~ "(?i)^(gif|png|jpe?g|webp)$") {

    # Set the Fastly Image Optimizer header
    set req.http.X-Fastly-Imageopto-Api = "fastly";
    
    #Run Class Logic
    if (req.url.qs ~ "(?:^|&)class=([^&]+)") {
      declare local var.pol STRING;
      set var.pol = table.lookup(io_classes, re.group.1, "");
      if (var.pol != "") {
        set req.url = req.url.path "?"
                      regsuball(req.url.qs, "(^|&+)class=([^&]+)", "")
                      "&" var.pol;
      }
    }
  }
  
  return (lookup);   
}

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.

Other helpful links:

Stay tuned — in a followup post I’ll discuss more ways for you to get the most out of Fastly IO, including how to deliver images based on device type and client preference, for reduced data usage.

Product Performance

You may also like:

Author

Dom Fee | Product Manager

Dom Fee is a Product Manager at Fastly, where he is responsible for image delivery products. Prior to Fastly, he was co-founder and product lead of ReSRC - the responsive image service Fastly acquired in 2015. When not working, he can be found cycling in the Yorkshire countryside, playing basketball with his two-year-old son, or sampling some of Leeds’ foodie hotspots.

dominicfee