English for Contentful CMS Developers
Vocabulary for developers integrating Contentful, the headless CMS platform — content models, entries, rich text, webhooks, and environments — for teams working across marketing and engineering in English.
Contentful is one of the most widely used enterprise headless CMS platforms — content teams manage entries through its web app, while engineers pull that content into websites and apps through its APIs. Because marketing, content, and engineering teams all use the same tool with different vocabularies in mind, being precise in English about “content models,” “entries,” and “spaces” avoids a lot of miscommunication in cross-functional meetings. This guide covers the terms.
Organisational Structure
Space — the top-level container in Contentful holding a content model, entries, and assets — roughly equivalent to a single project or environment for a specific app. “We have separate spaces for our marketing site and our product documentation — they don’t share content models at all.”
Environment — a version of a space’s content and schema you can work in independently, commonly used for testing schema changes before applying them to the live master environment.
“We built the new content model in a sandbox environment first, tested it thoroughly, then merged those changes into master.”
Organisation — the billing and user-management layer above spaces, typically shared across all the spaces a company owns.
Content Modeling
Content Type
A content type defines the schema for a category of content — its fields, validations, and appearance in the entry editor. It’s the Contentful term for what other CMSs call a “collection” or “schema.”
“We added a
relatedArticlesfield to theBlogPostcontent type — every existing entry now shows that field, empty until an editor fills it in.”
Entry
An entry is a single piece of content created from a content type — one instance, like one specific blog post created from the BlogPost content type.
“This entry has been sitting in draft for two weeks — can you check with the author whether it’s ready to publish?”
Asset
An asset is a media file (image, PDF, video) stored in Contentful, referenced by entries rather than duplicated per entry.
“We’re reusing the same hero asset across three campaign pages — updating the file once updates it everywhere it’s referenced.”
Rich Text Field
A rich text field stores structured, nested content (headings, lists, embedded entries) as JSON, rendered into HTML or React components by your app’s rendering logic.
“The rich text field lets editors embed a product entry directly inside an article — our renderer knows how to turn that reference into a product card.”
API and Delivery Vocabulary
Content Delivery API (CDA) — the read-only API serving published content, used by production apps.
Content Preview API (CPA) — a parallel API serving draft, unpublished content, used to preview changes before they go live.
“We point our preview deployments at the Content Preview API so editors can see unpublished changes before approving them.”
Content Management API (CMA) — the API used to programmatically create, update, or migrate content and content types, as opposed to just reading it.
“We wrote a migration script against the Content Management API to backfill the new
excerptfield across 400 existing entries.”
Localisation — Contentful’s built-in support for maintaining separate field values per locale within the same entry, rather than duplicating whole entries per language.
“The French and German versions of this entry share the same images and structure — only the localised text fields differ.”
Publishing Workflow
Published vs. draft state — an entry can have unpublished changes sitting alongside its live, published version; only the published version is served by the Content Delivery API.
Webhook — a configured callback Contentful fires when content changes (published, archived, deleted), commonly used to trigger a rebuild of a static site.
“Every time an editor publishes a change, the webhook fires and triggers our static site rebuild automatically — no manual deploy step.”
Content model migration — a scripted, versioned change to the content model (adding/removing fields, changing validations), run through the Management API rather than manually clicked through the UI, so changes are repeatable across environments.
“We wrote the field rename as a migration script and ran it against the sandbox environment first — that way the same script applies cleanly to master later.”
Explaining Contentful to a Cross-Functional Team
| Situation | Phrase |
|---|---|
| Explaining preview vs. live | ”What you see in the preview link includes your unpublished draft changes — customers won’t see any of it until you hit publish.” |
| Describing a webhook-triggered deploy | ”As soon as this entry is published, the webhook triggers a rebuild — the live site should update within about two minutes.” |
| Justifying environment-based testing | ”We test schema changes in a sandbox environment first, so a mistake in the field configuration never touches the live content model.” |
| Explaining localisation | ”You only need to translate the text fields — the layout and images are shared automatically across all locales.” |
Common Mistakes
- Calling a content type a “template” — a content type defines the schema/fields; a template usually implies a fixed visual layout, which is a separate concern.
- Confusing the Content Delivery API (published only) with the Content Preview API (includes drafts) — mixing them up in a bug report sends engineers looking in the wrong place.
- Saying “the CMS crashed” when an editor really means “the entry failed validation” — being specific about what actually happened saves debugging time.
Practice Exercise
- Explain, in two sentences, the difference between the Content Delivery API and the Content Preview API to a new engineer.
- Write a short note to a content editor explaining why their unpublished changes aren’t showing on the live site.
- Draft a migration plan summary for adding a new required field to an existing content type with 500 entries.