Platform Integration Deep Dives

This section governs how a frontend integrates with a specific headless CMS: the API contract it relies on, how drafts reach previews, how published changes reach caches, and how environments keep schema changes from breaking production. Every platform solves these problems differently, so the section pairs a common integration frame with deep dives into Contentful, Sanity, Strapi, Directus, Storyblok and Hygraph.

Integrating a headless CMS is more than calling its API. The integration has to enforce a data contract that survives editors changing the model, decide where content is cached and how it is invalidated, give editors a trustworthy preview, and fit the platform’s rate limits, query language and hosting model. The same six concerns appear in every integration, whether the CMS is a hosted SaaS product or a self-hosted application in your own cloud account, and handling them consistently is what separates integrations that run quietly for years from those that generate a steady stream of incidents.

Core Concepts & Terminology

Delivery API. The read API that serves published content to frontends, usually behind the vendor’s CDN: Contentful’s Content Delivery API, Sanity’s API CDN, Storyblok’s Content Delivery API, Hygraph’s Content API with the PUBLISHED stage, and the REST or GraphQL endpoints of self-hosted Strapi and Directus. It is the only API readers’ requests should ever depend on.

Preview path. The combination of a draft-capable API or parameter, a server-side token and a frontend draft mode that shows unpublished content to editors only. Each platform names it differently: Contentful’s Preview API, Sanity’s drafts perspective, Strapi’s status=draft, Directus content versions, Storyblok’s draft version and Hygraph’s DRAFT stage. The general patterns are in preview and draft workflow patterns.

Data contract. The typed shape of the content the frontend expects, generated from the CMS schema where possible and validated at runtime where it matters. Contracts turn schema changes into build failures instead of empty sections on live pages; see setting up TypeScript types from headless CMS schemas.

Revalidation event. A webhook sent on publish, unpublish or delete that tells the frontend which cached data is stale. Signed webhooks prove their origin; unsigned ones need a secret header. Every deep dive in this section includes a guide to securing them.

Environment. An isolated copy of schema and, depending on the platform, content, used to develop and test changes before production: Contentful environments and aliases, Sanity datasets, Directus schema snapshots across instances, Hygraph environments, Storyblok spaces, and separate Strapi deployments with their own databases.

Cache tag. A label attached to cached data, such as article:42 or article:list, that a revalidation event can invalidate precisely. Tags connect the CMS’s events to the frontend’s caches without full rebuilds.

Architecture Decision Frame

Four forces shape every integration in this section, and they explain most of the differences between the deep dives.

Hosting model. Hosted platforms such as Contentful, Sanity, Storyblok and Hygraph run the content store, APIs and CDN for you, with rate limits, plan-based features and the vendor’s release cadence. Self-hosted platforms such as Strapi and Directus give you data residency, custom code and no per-request pricing, and in exchange you run the database, backups, scaling, upgrades and security patches. The integration code on the frontend is similar; the operational surface is not.

Query model. REST APIs with population parameters, as in Strapi, Directus, Storyblok and Contentful’s REST API, push the shape of responses into query strings and favour CDN caching. GraphQL, native in Hygraph and available for most others, lets queries describe exactly the fields a page needs. GROQ in Sanity combines both ideas with projections. The trade-offs are covered in GraphQL vs. REST API trade-offs.

Schema location. Some platforms keep the schema in code, like Sanity’s Studio configuration and Strapi’s schema files, so changes arrive through pull requests. Others keep it in the platform, like Contentful, Storyblok, Hygraph and Directus, so changes must be exported, migrated or generated into code. Where the schema lives decides how type generation and schema migrations work.

Editorial experience. Visual editors, such as Storyblok’s Visual Editor and Sanity’s Presentation tool, make the frontend part of the editing interface, which raises the bar for draft rendering and click-to-edit support. Form-first editors, such as Directus and Hygraph, put less pressure on the frontend but need good previews to earn editors’ trust.

Delivery Plane: Fetching, Caching and Invalidation

The delivery plane is where readers’ experience is decided, and the principles are the same on every platform. Fetch on the server with one helper per platform that chooses published or draft content from the frontend’s draft mode, so no fetch path can accidentally show drafts or forget them. Select only the fields a page renders, whether through GraphQL selections, GROQ projections or REST fields and populate parameters; over-fetching is the most common cause of slow pages and rate-limit problems in headless builds.

Cache published responses with tags per entry and per list, and invalidate them from verified webhooks. Cache-Control headers and a stale-while-revalidate window keep pages fast while fresh content is fetched in the background; the semantics are summarised in MDN’s HTTP caching reference. Several platforms also cache on their side: Storyblok’s cache version, Hygraph’s cached endpoint and Sanity’s API CDN each need their own attention, so a revalidated frontend does not simply refetch a stale API response.

Webhooks deserve particular care because they are the only path by which the CMS tells the frontend that something changed. Verify them: HMAC signatures on Contentful, Sanity, Storyblok and Hygraph, a secret header on Strapi and Directus. Subscribe only to events that change what readers see, map payloads to tags in one place, make handlers idempotent, and keep a scheduled backstop for missed deliveries. Guides for each platform: Contentful, Sanity, Strapi, Directus, Storyblok and Hygraph.

Management Plane: Schemas, Environments and Contracts

The management plane is where most integration incidents begin: a renamed field, a relation that became optional, a new block type the frontend does not know. The defence is the same everywhere. Generate types from the schema and fail CI on drift: Contentful’s type generators, Sanity TypeGen, Storyblok’s CLI, GraphQL codegen for Hygraph and the GraphQL APIs of Strapi and Directus. Validate critical content at runtime, because types describe what the schema allows, not what old entries actually contain.

Change schemas through environments. Contentful’s environment aliases switch production to a migrated environment atomically; Sanity uses datasets per environment with migrations; Directus applies schema snapshots across instances; Strapi keeps schema in code and migrates the database on deployment, which makes major upgrades a frontend concern too. Whatever the mechanism, follow expand and contract: add new fields first, move the frontend, then remove old fields, as described in migrating content models without breaking the frontend.

Access control belongs to this plane as well. Every platform distinguishes public or published read access from draft access and from write access; keep them in separate tokens, all on the server, each with the narrowest scope that works. Self-hosted platforms add permissions you configure yourself, as in Strapi’s roles and API tokens and Directus access policies; keep those permissions in code or snapshots so environments never drift apart.

Preview and the Editorial Loop

Preview is where editors decide whether they trust the integration. A good preview renders drafts with the real frontend, updates quickly after edits, never leaks to readers, and works for every content type and locale. The mechanics differ: Sanity’s Presentation tool and Storyblok’s Visual Editor embed the site and edit in place; Strapi’s preview handler, Hygraph’s content stages and Directus content versions open the site in draft mode from a button. The security rules are shared: validate a secret before enabling draft mode, fetch drafts with a server-only token, bypass shared caches, send noindex, and keep sitemaps, feeds and search indexing on published content only.

Platform & Tooling Landscape

Contentful Integration Guide. A hosted, API-first CMS with REST and GraphQL delivery APIs, a separate Preview API, environments with aliases for zero-downtime schema changes, and rich text with embedded entries. Integration work centres on rate limits, include depth and the sync API for large builds.

Sanity Studio Customization. A hosted Content Lake with a Studio configured in code, GROQ queries with projections, perspectives for drafts, TypeGen for typed queries, GROQ-powered webhooks and visual editing with stega-encoded source maps.

Strapi Self-Hosted Setup. An open-source Node.js CMS you run yourself, with REST and GraphQL APIs, Draft & Publish, roles and API tokens, an upload provider for object storage, and a major-version upgrade from 4 to 5 that changed the response format.

Directus Data Layer Patterns. A self-hosted data platform that wraps an SQL database with REST and GraphQL APIs, access policies, flows for automation, content versioning and schema snapshots, suited to teams whose content lives alongside relational data.

Storyblok Visual Editor Integration. A hosted CMS built around nestable blocks and a Visual Editor that shows the frontend while editors compose pages, with draft and published versions, a cache version for CDN freshness and relation resolution parameters.

Hygraph GraphQL Content Federation. A hosted GraphQL-native CMS with content stages for drafts, localization with fallback lists, signed webhooks and remote sources that federate external APIs into the content graph.

Across platforms, the same tools recur on the frontend: Next.js draft mode and tag-based revalidation, GraphQL codegen or platform-specific type generators, runtime schema validation for critical content, and a small set of shared helpers for fetching, links, images and rich text. The automated testing and caching strategies sections cover them in depth.

Choosing Between Platforms

Platform selection is covered in depth in headless CMS architecture and platform selection, but a few integration-driven questions narrow the choice quickly. Must content stay in your own infrastructure or region? Self-hosted Strapi or Directus, or a hosted platform with the right region. Do editors build pages from sections themselves? Storyblok’s blocks or Sanity’s Presentation tool. Is the content deeply relational and shared with other systems? Directus over an existing database, or Hygraph with remote sources. Do many teams consume the content through different channels? Contentful’s mature APIs and environments, or Sanity’s flexible queries. Is the team small and comfortable with code? Sanity or Strapi, where the schema lives in the repository.

No platform is best at everything, and the integration effort differs less than vendors suggest: every option needs a typed data layer, a preview path, verified webhooks and environments. Choose on editorial fit and operational ownership, then invest in the shared integration patterns this section describes.

Operational Concerns

Rate limits and build load. Hosted platforms limit uncached requests; static builds over thousands of entries must paginate, bound concurrency and retry 429 responses, as shown for Hygraph and Contentful. Incremental builds and on-demand rendering keep build load proportional to change rather than to catalogue size.

Self-hosted operations. Strapi and Directus need the operational basics of any production application: stateless instances, managed databases with backups, object storage for uploads, secrets management, monitoring, and a patch and upgrade routine. Self-hosting Strapi on AWS and Strapi uploads on S3 behind a CDN show what that looks like in practice.

Observability. Log every CMS request with platform, operation, draft or published, status and duration; log every webhook with the entry and tags revalidated; alert on signature failures, rate-limited responses and unknown content types. A synthetic freshness check, which publishes a heartbeat entry and measures how long it takes to appear on the site, catches broken webhooks before editors do.

Failure modes. CMS outages should degrade to cached pages, not errors: serve the last good response when the delivery API fails, and fail builds loudly rather than publishing incomplete sites. Remote data, such as prices federated through Hygraph, needs explicit fallbacks. Unknown block types and missing required fields should render nothing for readers and a clear placeholder in preview.

Runbooks. Keep short runbooks for the recurring situations: a stale page after publishing, a preview showing published content, a failed schema migration, a rotated token. Each deep dive’s troubleshooting sections are a starting point.

Worked Example

A media group consolidated four brands onto a common frontend platform while each brand kept its CMS: two on Contentful, one on Sanity and one on Storyblok. The platform team built one integration frame with per-CMS adapters: a fetch helper with draft mode, generated types with CI drift checks, a webhook handler per CMS with signature verification and tag mapping, and a shared freshness check. Before, each brand had its own ad-hoc integration and its own class of incidents. After a year on the shared frame, CMS-related incidents fell by more than two thirds, and adding a fifth brand on Hygraph took weeks rather than months, because only the adapter was new.

Team and Ownership

Integrations have three kinds of owners. Platform or frontend engineers own the data layer, types, webhooks, preview routes and the operational side of self-hosted CMSs. Content designers own the content model together with engineers, because every field is part of an API. Editors own entries, releases and publishing, and are the first to notice when preview or freshness breaks. Write down who may change the schema in which environment, route schema changes through pull requests that include the frontend work, and give editors a documented way to report integration problems with the information engineers need: the entry, the environment and what they expected to see.

Common Anti-Patterns

Tokens in the browser. Draft or write tokens shipped in client bundles are public. Keep every token on the server, and use public, published-only access for anything the browser must fetch directly.

Preview by query parameter. Showing drafts whenever ?preview=1 is present exposes unpublished content to anyone. Draft mode must be enabled only after validating a secret.

Unverified webhooks. Endpoints that revalidate on any request can be abused to overload the origin. Verify signatures or secret headers before doing any work.

Rebuilding everything on every event. Full rebuilds on each publish waste build minutes and delay content. Use tag revalidation, or debounce builds for static sites.

Hand-written types. Interfaces written by hand drift from the schema silently. Generate them and check for drift in CI.

Wildcard purges. Clearing the whole CDN on every publish floods the origin. Purge by tag or path.

Measuring Success

Measure integrations by outcomes that editors and readers notice. Publish-to-live time, measured by a heartbeat check, shows freshness. Preview adoption and the number of publish-then-unpublish events show whether editors trust previews. Build duration and API usage show efficiency. Incidents by cause, such as stale content, broken preview or schema mismatch, show where the integration is weak. Review these numbers quarterly, compare them across platforms when several are in use, and use them to decide where to invest next.

Migrating Between Platforms

Sooner or later, many teams move content from one CMS to another, because of pricing, editorial needs or consolidation. The integration frame makes that far less painful than it sounds. With a typed data layer, pages depend on the frontend’s view models, not on the old CMS’s response format, so the migration replaces adapters rather than components. Plan it in the same phases as a major upgrade: model the content in the new platform, write an import that maps entries, references and assets, run both platforms in parallel behind a flag while comparing rendered pages, and switch over type by type. Keep URLs stable, redirect those that must change, and migrate webhooks and preview routes together with each content type, so editors never work in a system whose changes do not reach the site. The legacy system decoupling strategies describe the same approach for moving off a monolithic CMS.

Security Across Platforms

The security posture of a headless integration comes down to a handful of rules that apply to every platform in this section. Keep all tokens on the server, scoped to the narrowest permission that works, rotated on a schedule and stored in a secret manager rather than in repositories. Authenticate every inbound request from the CMS, whether webhooks or preview launches, before doing any work. Keep draft content behind validated draft mode and out of shared caches, feeds and sitemaps. On self-hosted platforms, add the usual application security basics: patched dependencies, private networks for databases, TLS with verified certificates, and admin panels behind single sign-on or at least strong authentication. Review permissions whenever a new content type is added, since new types are where accidental public access most often appears.

Implementation Checklist

• Choose the platform on editorial fit and operational ownership, not on integration effort alone.
• Build one fetch helper per platform that selects published or draft content from draft mode.
• Generate types from the schema and fail CI on drift.
• Validate critical content at runtime and render safe fallbacks.
• Keep published, draft and write tokens separate and on the server.
• Validate a secret before enabling draft mode, and keep drafts out of caches, feeds and sitemaps.
• Verify every webhook, subscribe only to reader-visible events, and map payloads to cache tags.
• Handle the platform’s own caches, such as cache versions and API CDNs.
• Change schemas through environments with expand and contract.
• Paginate large collections with bounded concurrency and retry rate-limited requests.
• Run self-hosted platforms statelessly with managed databases, object storage and backups.
• Log requests and webhooks, and measure publish-to-live time with a heartbeat.

Frequently Asked Questions

Related

• Contentful Integration Guide
• Sanity Studio Customization
• Strapi Self-Hosted Setup
• Directus Data Layer Patterns
• Storyblok Visual Editor Integration
• Hygraph GraphQL Content Federation