Managing images effectively is key to creating engaging user experiences. Developers need tools that make their jobs easier, help applications perform better, and be more adaptable. Contentful’s Image API offers robust features for handling, transforming, and optimizing images through API requests.
Contentful is an industry-leading Content Management System that allows developers and businesses to efficiently manage and deliver content across various channels. Its Image API enables more than just basic image retrieval and format changes. It includes advanced options like resizing, cropping, and improving image quality. These features let developers adjust images for different situations, ensuring they load quickly and look good on any device.
In this article, we’ll go over how Contentful’s Image API can give you a built-in way to manage your images with simple transformations and image optimization. Then, we’ll show you how you can take advantage of tools like Cloudinary to transform images on a whole different level.
In this article:
- Getting Around with the Contentful Image API
- Resizing and Cropping Images
- Improving Image Quality
- Controlling Background Color Using the Contentful Image API
- Accessing Progressive JPEGs and 8-bit PNGs
- Dealing with Image Deletion
- Maximize the Impact of Your Images with Cloudinary
Getting Around with the Contentful Image API
Contentful’s content management approach, including images, is powered by its own Contentful Images API. This API allows you to retrieve and manipulate images already uploaded to your Contentful account, giving you access to essential image management features.
Note: The Contentful Image API only refers to images under 20MB. Any image with a larger file size is considered an ‘asset’ and does not work with this API.
Retrieving Images with the Contentful Image API
Getting started with images stored in Contentful means understanding how to retrieve them using the API. Each image in Contentful can be accessed through a unique ID associated with your space’s assets. To fetch an image, you make a GET request to the Contentful API endpoint with the asset’s ID. Here’s an example of how you might do this:
You could set up your API call as follows:
GET https://images.ctfassets.net/{space_id}/{asset_id}/{unique_id}/{name}
This call will return the image you requested in its original format. This information is based on the file.url field of an asset within Contentful.
Imagine you’re developing a gallery feature and must display multiple images from Contentful. By constructing URLs dynamically based on the asset IDs and desired parameters, your application can efficiently load only the necessary data, enhancing performance and reducing bandwidth use.
Changing Image Formats with the API
Contentful’s Image API also excels at transforming images into different formats directly through API calls, which is essential for ensuring compatibility across different browsers and devices.
For example, to convert an image from JPEG to WebP for browsers that support it, enhancing compression, your API call might look something like this:
GET https://images.ctfassets.net/{space_id}/{asset_id}/{unique_id}/{name}?fm={image_format}
By simply appending ?fm=webp to your API request, you instruct Contentful to deliver the image in WebP format. This helps your images load faster without compromising on quality.
Resizing and Cropping Images
When you need to adjust the dimensions of an image to suit different elements on a webpage or application, Contentful’s API simplifies this task. Adding parameters to your image request lets you specify the required size and aspect ratio. For instance, if you want to resize an image to 300×300 pixels, your API request would include parameters like this:
GET https://images.ctfassets.net/{space_id}/{asset_id}/{unique_id}/{name}?w=300&h=300
Cropping is just as straightforward. You might need to focus on a particular part of an image, such as centering on a subject or removing unwanted edges. Using the fit parameter, you can dictate how the image should be cropped and resized. This might look something like:
GET https://images.ctfassets.net/{space_id}/{asset_id}?w=300&h=300&fit=crop&f=face
Here, the API resizes the image and ensures that the cropping focuses on any detected faces, making it ideal for profile images or thumbnails where a person (or people) is the focal point.
Improving Image Quality
Contentful also offers parameters that enhance the quality of the images served. This is particularly useful when dealing with images that must look sharp under varying screen resolutions and sizes. The API allows you to specify a quality level for JPEGs or a compression level for PNGs, which can help reduce bandwidth usage without noticeably degrading image appearance. An example API call to enhance image quality might be:
GET https://images.ctfassets.net/{space_id}/{asset_id}/{unique_id}/{name}?q=80
This request specifies that the image should be served with a quality setting of 80 (out of 100), effectively balancing quality and file size. Though it’s fairly limited in options, adding additional tools like Cloudinary’s Image API can help bring out the best in your photos (while still integrating with the Contentful Image API).
Controlling Background Color Using the Contentful Image API
When dealing with images that have transparent backgrounds, such as PNGs, you might sometimes need to specify a background color. This is especially useful for product images on e-commerce sites where a consistent background is necessary. The API allows you to set a default background color with a simple parameter:
GET https://images.ctfassets.net/{space_id}/{asset_id}/{unique_id}/{name}?bg=rgb:ffffff
This example sets the background color to white, replacing any transparency in the image with a solid white background, enhancing consistency across your site.
Accessing Progressive JPEGs and 8-bit PNGs
Progressive JPEGs are a great alternative to traditional image formats for websites. They load in successive waves, becoming progressively clearer with each pass. This can improve perceived performance, as users see a low-quality version of the image fill in gradually rather than waiting for the entire file to download.
To request a Progressive JPEG, you would modify your API call like so:
GET https://images.ctfassets.net/{space_id}/{asset_id}/{unique_id}/{name}?fm=jpg&fl=progressive
Similarly, the Contentful Image API offers limited support for 8-bit PNG, which is ideal for simpler images or icons where a limited color palette is sufficient. The request would look something like:
GET https://images.ctfassets.net/{space_id}/{asset_id}/{unique_id}/{name}?fm=png&fl=png8
Dealing with Image Deletion
Managing your digital assets includes deleting old or unused images too. When the time comes to delete an image, Contentful requires you to use their Asset API, not their Image API. To delete an image, you would make a DELETE request to the Contentful API endpoint like so:
DELETE https://api.contentful.com/spaces/{space_id}/environments/{environment_id}/assets/{asset_id}
This request will permanently remove the asset from your space, provided all validations and conditions, such as authentication and authorization, are met. Contentful then removes all previously referenced files within its CDN, too. Don’t be alarmed if you don’t see immediate results, though, as this process can take up to 48 hours.
Deleted assets are irrecoverable, emphasizing the need for implementing proper checks and balances before performing such operations. Deleting an image should be taken seriously, as it affects how content is served and managed. Implementing a soft delete feature or archiving images before permanently deleting them can be a good idea, giving you a buffer to restore files if needed.
Maximize the Impact of Your Images with Cloudinary
While Contentful offers powerful content management solutions, their Image API falls short for anything beyond simple manipulations. Cloudinary’s service blends well with Contentful’s features by providing advanced image and video management options essential for dynamic and visually driven applications.
Cloudinary excels in areas requiring extensive image manipulations, offering tools for automated transformations, optimizations, and delivery adjustments based on the end user’s device and network conditions. Unlike the Contentful Image API, which offers limited support for images beyond cropping and changing image formats, Cloudinary provides a supercharged solution that can:
- Deliver images in almost any image format
- Optimize images on the fly
- Add, remove, or expand backgrounds with Generative AI
- Transform images with filters, overlays, and smart cropping
- Upscale images to make products shine
- And so much more
Let’s consider a use case where you’re dealing with high volumes of images, such as in an e-commerce platform. Cloudinary can automatically resize, crop, and adjust the quality of product images on the fly, ensuring they are perfectly optimized for mobile and desktop views. This improves load times and enhances the visual appeal of your product listings across different platforms.
Cloudinary supports advanced features such as AI-based tagging and analysis, which can automatically categorize and tag images based on their content. This feature is incredibly useful for creating searchable image databases and improving asset discoverability.
Integrating Cloudinary with Contentful significantly streamlines your workflow. You create a cohesive ecosystem leveraging both platforms’ strengths by handling image uploads and transformations through Cloudinary and managing content relationships and delivery through Contentful. So what are you waiting for? Sign up for free today.