What is the Contentful Image API and How Does it Work?

The Contentful Images API is a powerful tool that enables developers to retrieve and manipulate image files referenced from assets.

Operating through a read-only Contentful Image API with the base URL "https://images.ctfassets.net", it provides essential image management capabilities.

The Contentful Image API has some important technical limitations that include:

• Maximum image size of 20MB for API processing
• Images exceeding 20MB are treated as assets without transformation features
• EU data residency customers must use https://images.eu.ctfassets.net
• 9 Megapixel limit for AVIF format transformations

Some further technical limitations also include the following:

Understanding how Contentful Image API represents images, starts with its JSON structure. Each asset contains essential information including:

• Title of the image
• File details (filename, content type)
• Image dimensions (width and height)
• File size
• URL for accessing the image

The JSON representation looks like this:

"fields": {
    "title": "Playsam Streamliner",
    "file": {
      "fileName": "quwowooybuqbl6ntboz3.jpg",
      "contentType": "image/jpg",
      "details": {
        "image": {
          "width": 600,
          "height": 446
        },
        "size": 27187
      },
      "url": "//images.ctfassets.net/[space-id]/[asset-id]/[unique-id]/[name]"
    }
  }

To retrieve images, developers can use the URL specified in the file.url field, which provides direct access to the original image.

Understanding the Image Retrieval Endpoint Using Contentful Images API

The basic image retrieval endpoint in Contentful follows this structure:

GET https://images.ctfassets.net/{space_id}/{asset_id}/{unique_id}/{name}

Breaking Down the URL Components

1. Space ID (`{space_id}`)
   • What: Alphanumeric identifier for your Contentful space
   • Example: `yadj1kx9rmg0`
   • Purpose: Identifies the specific content space where your assets are stored
   • Required: Yes
   • Format: Alphanumeric string
      
2. Asset ID (`{asset_id}`)
   • What: Unique identifier for the specific asset
   • Example: `wtrHxeu3zEoEce2MokCSi`
   • Purpose: Points to the particular asset within your space
   • Required: Yes
   • Format: Alphanumeric string
      
3. Unique ID (`{unique_id}`)
   • What: Additional identifier ensuring image uniqueness
   • Example: `cf6f68efdcf625fdc060607df0f3baef`
   • Purpose: Provides version control and cache management
   • Required: Yes
   • Format: Alphanumeric string
      
4. Name (`{name}`)
   • What: Original filename of the image
   • Example: `quwowooybuqbl6ntboz3.jpg`
   • Purpose: Maintains original file reference and extension
   • Required: Yes
   • Format: String with file extension

Basic Request

curl --include \
    --request GET \
    "https://images.ctfassets.net/yadj1kx9rmg0/wtrHxeu3zEoEce2MokCSi/cf6f68efdcf625fdc060607df0f3baef/quwowooybuqbl6ntboz3.jpg"

Response

Status: 200 OK

Body: Raw image data

Content-Type: Based on image format (e.g., image/jpeg, image/png)

Contentful supports multiple image formats to ensure optimal delivery across different platforms and use cases. Supported formats include

1. JPG
2. PNG
3. WebP
4. GIF
5. AVIF
6. TIFF

The Contentful Images API allows for format conversion through simple URL parameters. Two specialized format options deserve particular attention:

Progressive JPEGs

Progressive JPEGs offer a superior loading experience by displaying the image in multiple passes of increasing quality. This approach:

• Shows a lower quality version initially
• Gradually improves detail during loading
• Maintains layout stability
• Enhances perceived performance

8-bit PNGs

8-bit PNGs are optimized for simpler images:

• Support up to 256 colors
• Smaller file size compared to 24-bit PNGs
• Ideal for icons and logos
• Better performance for simple graphics

For AVIF format specifically, there's a 9 Megapixel limit on source images across all service tiers.

Contentful provides robust resizing and cropping capabilities through its API:

Dimension Specifications

• Maximum allowed dimension: 4000 pixels
• Width and height can be specified independently
• Original dimensions are used by default

Resizing Behaviors

Five different fit options are available:

1. pad: Resizes with padding to maintain dimensions
2. fill: Resizes and crops to fit specified dimensions
3. scale: Resizes while potentially changing aspect ratio
4. crop: Crops part of the original to fit dimensions
5. thumb: Creates a thumbnail version

Focus Area Options

When using fit types (pad, fill, crop, or thumb), you can specify focus areas:

• center, top, right, left, bottom
• top_right, top_left, bottom_right, bottom_left
• face (largest face detected)
• faces (all detected faces)

Rounded corners and circular cropping can be achieved using the radius parameter, with options for:

• Specific pixel values for corner radius
• 'max' keyword for full circle/ellipse
• Default value of 0

Contentful offers several key parameters for optimizing image delivery and appearance:

Quality Control

1. Quality can be adjusted using percentage values between 1 and 100
2. Quality settings affect all formats except 8-bit PNGs
3. Higher values maintain better image quality but increase file size

Background Color Management

Background colors can be specified for images using RGB values

• Format: rgb:9090ff (example)
• Default settings:
  • White for JPEGs
  • Transparent for PNGs and WEBPs
• Particularly useful when:
  • Using corner radius features
  • Implementing the pad fit type
  • Maintaining consistent image presentation

To effectively implement the Contentful Image API, construct URLs using this pattern:

GET https://images.ctfassets.net/{space_id}/{asset_id}/{unique_id}/{name}

For dynamic image manipulation, append parameters to the base URL:

1. Format changes: ?fm=webp
2. Dimension adjustments: ?w=300&h=300
3. Quality settings: ?q=80
4. Combined parameters: ?w=300&h=300&fit=crop&f=face

Deletion Process

1. Images must be deleted through the Content Management API (CMA), not the Contentful Image API
2. Use a DELETE request to the following endpoint:

DELETE https://api.contentful.com/spaces/{space_id}/environments/{environment_id}/assets/{asset_id}

Important Considerations

• Deletion is permanent and irreversible
• CDN cleanup can take up to 48 hours
• All previously referenced files within the CDN will be removed
• Implement proper validation before deletion

This process requires careful management as it directly impacts content delivery and overall system integrity.

Suitable for simple requirements with features like conversion of formats, resizing, and simple optimization, it lacks support for things like the 20MB file limit and limited manipulation features.

The secret is taking advantage of Contentful's capabilities for simple image management, but ready to blend in other tools as needed for more advanced demands.

This hybrid strategy promotes the most efficient image delivery with room to scale up when necessary.