Developing with the Contensis Image API

The 11.3 release has been largely based around improving the experience of using images in Contensis. Content authors can now easily upload, crop, and publish images. Admins can restrict the size and orientation these are delivered at. But what about developers?

Introducing the new Image API

Our new Image API gives developers more control over how images are rendered to the front-end, no matter the device. This API improves massively over the previous cached image handler, and can deliver images a fraction of their original size but without a significant loss of quality.

The Image API applies transformations in real time and caches the results for fast delivery.

It allows you to:

These are applied by adding a query string to the URI of the image. For example:

https://www.contensis.com/image-library/blog-images/tree-frog.jpg?width=500

Combining the Image API with the new features of the image editor in Contensis gives you much more control over how images are displayed. You can make full use of the srcset attribute to deliver the appropriate size and resolution image to any device. Authors can select different creative crops of the same image to be displayed on desktop and mobile.

Resize

You resize an image by appending the width or height (or both) parameter to the image query string. This allows an author to upload a large high-resolution image while giving the developer an easy way to serve it at an appropriate size for the device or situation in which it's displayed.

Crop

The crop parameter controls how the image is cropped, scaled, and aligned. Crops can be from top, right, bottom, centre or set manually with specific coordinates. More details can be found in the Image API crop documentation.

Rotate and flip

You can rotate images by using the rotate parameter with the value set to an integer between 0 and 359. You can also flip an image by using the flip parameter with a value of horizontal, vertical, or both. Perfect for reversing an image to make it better fit a layout.

Grayscale and blur

Images can be made grayscale by using the effect parameter with a value of grayscale. Blur can be applied by setting the blur parameter to a value between 1-100.

Format

The format parameter allows the conversion of one image format to another. Allowed values are jpg, png, and webp.

Quality

Image quality is controlled by the quality parameter. A value between 0 and 100 sets the compression level.

Caching

Images served with the image API are set to be cached for a year, meaning they don’t have to be re-downloaded every time the user visits the site. Contensis adds a unique hash to the file name so if the image changes the browser will not serve the old one. Read more about Image API caching.

Advanced examples of using the Image API

We designed the Image API to support a number of modern development techniques.

Automatically setting an image to resize using srcset

Even if an image has been saved in Contensis at full size, it can be processed and delivered to the browser at the optimum size for the device or connection speed.

Using the srcset attribute, an image can be displayed at different sizes depending on the device size and resolution.

Creating an image component and using the picture element

Using a simple component in Contensis, you can allow an editor to create 3 different crops of the same image and use the picture element to display them. This is especially powerful as it allows an editor to artistically crop an image to best fit the device or aspect ratio it’s displayed in.

In your code, you can then use the picture element to display a different image depending on the available space. Here’s an example:

Using a modern web format

WebP is a modern image format developed by Google. WebP images are generally around 25-34% smaller than a comparable JPEG image. This means they load quicker and use less data than older formats.

WebP is a relatively new format and isn’t supported by all browsers (WebP compatibility chart). The Image API detects if the browser is compatible and will serve a standard JPEG if it isn’t.

Try it now!

The Image API is available in Contensis 11.3 and higher and can be easily applied to any image served by Contensis. Just add the query string to any image in your templates, Razor views, or React apps to serve higher quality, better optimised images in a modern format.

Check out the full Image API documentation.