How it works

Contentful is a headless CMS — it stores and manages content separately from the front end. Instead of building pages in a CMS admin, you pull structured data through an API and render it however you want. This integration uses Django + the Contentful Delivery API to do exactly that.

Key concepts

🗂️Space

A Contentful workspace. Everything lives inside one space — its content types, entries, and assets. Accessed via a Space ID.

📐Content Types

The schema layer. A content type defines what fields exist and what types they are — like a model or database table definition.

📄Entries

The actual content. Each entry belongs to a content type and has values for each field — the equivalent of a database row.

🖼️Assets

Files — images, videos, PDFs. Hosted on Contentful's CDN at images.ctfassets.net with on-the-fly transforms.

How this integration is built

Connect to the Delivery API

All reads go through cdn.contentful.com using a read-only access token. No SDK needed — just HTTP requests. The base URL includes the Space ID and environment.

GET https://cdn.contentful.com/spaces/{SPACE_ID}/environments/master/entries ?access_token={DELIVERY_KEY} &content_type=blogPost&include=2

Introspect the schema at runtime

Rather than hardcoding field names, the integration calls /content_types to discover the schema dynamically — field names, types (Symbol, RichText, Link, Array), and which types link to which.

# Field types you'll encounter Symbol → short text RichText → document AST (not HTML) Link → reference to another entry or asset Array → list of links or short texts Boolean → true / false

Resolve linked entries with include

Contentful entries can link to other entries and assets by ID. Adding ?include=2 tells the API to resolve those links in one request — up to 2 levels deep — returning them in a top-level includes object.

# Response shape with include=2 { "items": [ /* main entries */ ], "includes": { "Entry": [ /* linked entries */ ], "Asset": [ /* linked assets */ ] } }

Serve images via the Images API

Every Contentful asset URL accepts query parameters that transform the image at the CDN edge — format conversion, resizing, cropping — before it hits the browser. A custom Django template tag wraps this cleanly.

# Custom template tag {% load ctf_tags %} {% ctf_img asset.url w=800 h=450 fit="fill" fm="webp" q=80 as img_url %} {{ asset.title }}

# Produces https://images.ctfassets.net/…?fm=webp&w=800&h=450&fit=fill&q=80