User Manual

Image Caching API

While Interface allows you to upload any type and size of images that you set in Models, you may have noticed that there is no resizing options in the admin. We actually did this on purpose.

If you want to resize your uploaded images for use on the front-end of your website, we provide an Image Caching API. This allows you to request an image and pass in sizing parameters. The Image Caching API then resizes your image (if it hasn’t been already), caches it, and serves it up.

Usage

The Image Caching API allows you to define an infinite amount of sizing options for your images. To access the API, all you have to do is prepend /image_cache/ to any image path. You can also use the ERB image tag helper and it will automatically handle using the Image Caching API for you.

If you want to access the Image Caching API outside of templates (for instance, in Flash), use the following reference to build the URL:

Example Base URL: /image_cache/assets/0000/0001/image.jpg

Add the following in a query string to modify the image:

  • w — The width to resize the image to, maintaining the image’s aspect ratio. Takes precedence over h if both are set.
  • h — The height to resize the image to, maintaining the image’s aspect ratio.
  • force — Set to true to force the dimensions on the image resize, ignoring aspect ratio of the image.
  • wx — Set to true to only resize the image if the image exceeds the width specified in w. Useful for not resizing images up if they are smaller than the requested resizing measurement.
  • hx — Set to true to only resize the image if the image exceeds the height specified in h. Useful for not resizing images up if they are smaller than the requested resizing measurement.
  • colors — Restrict the amount of colors on the resized image.
  • quality — The quality on the resized image, from 0 to 100. This does not affect PNG files (use colors instead).

Example URLs

Resize to 200 pixels wide:

/image_cache/assets/0000/0001/image.jpg?w=200

Resize to 200 pixels wide, only if the image exceeds 200 pixels:

/image_cache/assets/0000/0001/image.jpg?w=200&wx=true

Force to resize to 200×100 pixels:

/image_cache/assets/0000/0001/image.jpg?w=200&h=100&force=true

Resource Considerations

We built the Image Caching API to be as efficient as possible, but it is still a fairly resource-intensive process and should only be used if you are actually manipulating the images you are requesting. Even if the image is already cached, it is still one extra step to look for the image and serve it. That means if you are using the Image Caching API but not resizing an image, it will be slightly slower than using the regular path to that image.

You may also consider compressing the image using the colors and/or the quality parameters to keep filesizes to a minimum.