We use cookies to make your viewing experience better. By accepting you consent, you agree to our Cookie policy

Improve your Craft CMS skills

Using Craft CMS Headless

10 min read
Andy Golpys, Co-Founder of MadeByShape

Decoupling content from presentation unlocks game-changing flexibility for digital experiences. This guide dives into using Craft CMS in headless mode to deliver omnichannel content with developer freedom. Read on to explore the capabilities of headless Craft CMS for customizable content delivery, dynamic pages, and seamless integration across channels.

Craft CMS enables headless content delivery via JSON APIs, allowing omnichannel publishing. It decouples content from presentation for greater flexibility. Headless Craft provides content portability across channels like web, mobile, IoT and digital displays while optimizing workflows and developer experience.

Understanding Headless Content Management Systems

What is a Headless CMS?

A headless CMS is a content management system that separates the content layer from the presentation layer. Unlike traditional CMS platforms that bundle content creation tools with front-end delivery, a headless CMS decouples these functions.

With a headless CMS, content is stored in a backend repository and accessed via APIs, rather than being served up directly to webpages. This allows the content to be delivered to any channel, platform or device. For example, content created in a headless CMS could be accessed by a website, mobile app, digital signage, IoT devices, etc.

The key advantages of this decoupled architecture include greater flexibility, omnichannel content delivery, and easier front-end development. Developers are not limited by the CMS templating system and can build pixel-perfect experiences using the framework of their choice.

The headless CMS simply serves structured content via API which the front-end then consumes and renders as needed.

Overall, headless CMS offers organisations the agility to deliver content across channels, touchpoints and devices. It future-proofs content, improves developer experience, and enables highly custom experiences honed to user needs.

How Headless CMS Works

Under the hood, a headless CMS separates the back-end content repository from front-end delivery. The content repository stores and organises all content assets, which can include text, images, videos, documents and more. Authors and editors use the CMS interface to create, manage and update content.

Front-end systems access this content via Content APIs, most commonly REST or GraphQL APIs. These APIs allow the front-end to retrieve content in a structured format like JSON. The front-end developers can then use this structured content in their apps, websites or other touchpoints.

So in summary, the key aspects of how headless CMS works:

  • Separation of back-end and front-end

  • Content authors manage content in CMS repository

  • Content gets delivered via APIs, not templates

  • Front-end systems consume content as structured data (JSON, XML)

  • Content can be published across multiple channels and devices

This decoupled, API-based approach enables greater flexibility and omnichannel experiences compared to traditional CMS models.

Benefits of Headless CMS

There are several notable benefits to using a headless content management system:

Omnichannel Content Delivery: With the decoupled architecture, content is no longer locked into templates and can seamlessly be published across channels. Headless CMS enables true omnichannel experiences.

Front-end Control: Developers have complete control over the front-end with the freedom to build experiences using their framework of choice. There are no limitations imposed by the CMS templating system.

Scalability: Headless CMS is designed to support distributed content across channels. The API-based infrastructure scales seamlessly to handle increasing traffic.

Flexibility: Content is future-proofed and can be accessed on any device or platform. Companies can easily adopt new technologies without migrating content.

Faster Development: Front-end and back-end teams can work in parallel, enabling faster development cycles and rapid experimentation.

Headless CMS unshackles content from traditional web delivery, providing omnichannel flexibility, better front-end experiences and scalability for the future. For these reasons, many modern organisations are adopting headless CMS over legacy systems.

Overview of Craft CMS

Craft CMS Features

Craft CMS is a flexible, user-friendly content management system that offers a robust set of features and capabilities. Some of the key features of Craft CMS include:

  • Flexible Content Modeling: Craft allows you to create custom entry types, fields, and taxonomies to model content according to your needs. This structured approach improves SEO and organization.

  • User Management: Craft provides granular user permissions to control who can access and edit content within the CMS. Useful for managing multiple content creators.

  • Templating System: Craft comes with a powerful Twig templating system to control frontend presentation and deliver content across channels.

  • Dashboard and UI: The intuitive control panel and user interface make it easy for content editors to manage content.

Overall, Craft provides a robust set of features right out of the box to empower content creators and developers alike. The flexible system can handle a wide range of website and content management needs.

Using Craft CMS as Headless or Traditional CMS

A key advantage of Craft CMS is that it can be configured for use as either a traditional or headless CMS.

For traditional deployments, Craft renders content directly to webpages using its templating system. This is suitable for sites contained within Craft itself.

Craft can also be set up as a headless CMS by enabling its JSON APIs. These APIs allow external applications to retrieve content in a structured format. The APIs provide a decoupled way to deliver content to any channel.

To configure Craft as a headless CMS, you simply need to enable the JSON APIs from the settings panel. You can then access content from front-end applications by calling the APIs and consuming the JSON data. The presentation layer is handled separately from Craft.

This headless versatility means Craft CMS can power both traditional websites as well as omnichannel content delivery to apps, devices and more. The same structured content can be leveraged across channels.

Structured Content Management

A key strength of Craft is its structured approach to managing content. Instead of just pages and posts, Craft allows you to create custom entry types with dedicated fields, relations and taxonomies tailored to your content model.

For example, you can have an “Event” entry type with fields for location, date, time, speakers, partners etc. Taxonomies like event type or event category can be attached. This creates structured, semantic content optimised for SEO.

The custom entry types, fields and taxonomies allow your team to model content according to the business domain. Content inherits vital context through its structure.

This flexible structure also scales elegantly as the project evolves. New entry types and fields can be added without affecting existing content.

Craft CMS provides an advanced structured content model to future-proof content while optimising workflows. The custom content types power SEO and help manage complex content at scale.

Setting up Craft CMS as a Headless CMS

Installation and Configuration

To get started with headless Craft CMS, first install Craft on a web server or hosting environment. The open source Craft CMS can be downloaded from https://github.com/craftcms/cms.

After installation, there are a few key steps to configure Craft for headless delivery:

  • Install the Craft headless plugin which enables the JSON APIs needed for decoupled content delivery.

  • In settings, enable "Allow Requests to API Endpoints" to open up API access.

  • Create an API key and token for secure API authentication. Apply appropriate user permissions.

  • Configure environment variables, settings and config files as per the headless setup guide.

  • Set up a frontend app like React to consume the APIs and render content.

  • For production, ensure the API runs over HTTPS for security.

With these steps, Craft CMS is ready to serve content to any device or channel via its APIs. You can now model content and build engaging experiences using your frontend stack.

Content Modeling and Workflow

When modeling content for headless in Craft, you want to optimize around delivery across channels. Some tips:

  • Use custom entry types like "videos", "podcasts", "blog posts" etc. that make sense for your content.

  • Add relevant fields to each entry type for metadata needed in apps and devices. Like audio length for podcasts.

  • Use categories, tags and other taxonomies to segment and organise content.

  • Optimize editorial workflows around headless roles and permissions.

  • Facilitate discoverability of content via search, filtering and queries.

  • Streamline workflows with collaboration features like Workflow, Drafts etc.

  • Structure API responses for ease of consumption across endpoints.

The goal is to model content independently from presentation layer, focussing on semantics, structure and workflow efficiency. This creates reusable content that plays nicely with headless.

Securing the APIs

It's important to properly secure access to the headless Craft CMS APIs:

  • Require API authentication with access tokens so only approved apps/devices can retrieve content.

  • Set up user roles and permissions specifically for API access.

  • Enable rate limiting on API endpoints to prevent abuse.

  • Mandate HTTPS across all API requests and responses for encryption.

  • Conduct routine security audits and penetration testing on the APIs.

  • Implement standards like OAuth 2.0 and JSON Web Tokens for robust API security.

With thoughtful authentication, encryption, rate limiting and testing, the APIs can be locked down tightly. This ensures only authorized parties are able to consume content from the decoupled CMS.

Accessing Content from Headless Craft CMS

Content Delivery APIs

Craft CMS provides a comprehensive set of APIs for retrieving content in a headless architecture. The key endpoints include:

  • Entries API - Retrieve entries or posts of any content type like blog posts, videos, events etc.

  • Assets API - Get asset files like images, documents, audio files that are uploaded to Craft.

  • Categories API - Access any taxonomies like categories, tags or brands used to organize content.

  • Users API - Fetch authors or user accounts details.

The APIs allow retrieval of content by ID, slug, search parameters, related content and more. Authentication is required using an API key or access token.

For example, you can use the Entries API to get a blog post by slug, retrieve 5 latest podcast episodes, or search events by date. The APIs expose powerful flexibility to consume content.

Consuming and Displaying Content

On the front-end, the Craft CMS content APIs can be called from any app framework like React, Vue, Angular etc. The responses return content as structured JSON data.

The JSON can then be mapped to components and displayed as per the app UI requirements - a blog post component, event listing component etc. APIs should be called client-side from frontend code.

When consuming the APIs in apps, it's important to properly handle status codes, cache responses, and deal with errors gracefully. Components should be built to gracefully handle loading states and partial responses.

For optimum performance, API responses can be cached where suitable. The frontend app solely focuses on presentation, while Craft delivers structured content.

Content Localization and Translation

Craft CMS has robust support for localizing content across multiple languages and locales.

The content APIs can accept locale parameters to return content translated into the desired language. For example, passing 'de-DE' would retrieve German translations of content.

Localized fields, categories, assets and other content can be set up within Craft and exposed via the APIs. The frontend app can then dynamically display localized experiences based on the user's locale.

This enables global experiences where content is seamlessly translated across geos, languages and market customizations, while retaining semantic structure.

The Craft CMS APIs empower applications to tap into structured content on-demand and render localized experiences - unlocking the flexibility of headless CMS.

Developing Front-end for Headless Craft CMS

Consuming Craft CMS APIs

When building front-end applications with headless Craft, the Craft APIs need to be integrated to retrieve content. Here are some tips for consumption:

  • Call APIs from frontend framework code (React, Vue, Angular etc) using fetch, Axios or custom logic. Don't call from back-end.

  • Authenticate API requests securely with access tokens or API keys.

  • Handle errors, loading states and partial responses gracefully in UI.

  • Follow API documentation for parameters, headers, endpoints etc.

  • Structure components to consume API data. For example, Post component gets post content from Entries API.

  • Optimize API calls - don't retrieve same data repeatedly.

Example fetch call in React to get post by slug:

fetch('/entries/posts?slug=hello-world', {

headers: {

Authorization: `Bearer ${API_TOKEN}`



.then(response => response.json())

.then(data => {

// display post data


Displaying Retrieved Content

To display content from Craft APIs, frontend components need to be built out across appropriate pages and routes:

  • Map JSON data into components - Post component, Media component etc.

  • Dynamically generate pages from API data - Post page, Category page etc.

  • Call APIs at appropriate lifecycle points - on mount, on update etc.

  • Handle loading and error states in components during API calls.

  • Follow naming conventions between APIs and components for clarity.

  • Utilize CMS previews to view draft content.

This allows content from Craft to be populated across the frontend seamlessly. Content changes in Craft will reflect instantly.

Caching and Performance

For optimal performance with headless Craft CMS:

  • Implement caching of API responses where suitable - caching read-only content.

  • Utilize CDNs to cache assets near users. Craft supports CDN asset volumes.

  • Enable Craft CMS caching features like memcache, Redis etc.

  • Consider server-side rendering (SSR) to avoid re-fetching content.

  • Minify and bundle frontend assets. Lazy load non-critical resources.

  • Conduct performance audits and monitoring on frontend.

  • Check for unnecessary API requests. Optimize pagination.

With the right caching strategies and performance best practices, headless Craft CMS can deliver blazing fast experiences across channels.

Integrating Headless Craft CMS

Webhooks and CRON Jobs

Craft CMS provides webhooks and CRON jobs to automate workflows and integrate with other platforms.

Webhooks allow external services to be triggered when certain events occur in Craft. For example, send content to a translation API when a new entry is published.

CRON jobs enable scheduled tasks to be run on a recurring basis. Useful for syncing content to other systems on a fixed interval.

Some examples of using webhooks and CRON with headless Craft:

  • Sync products to ecommerce when commerce entries are updated.

  • Send new blog posts to Slack or Microsoft Teams when published.

  • Crawl content APIs and update search index nightly with CRON.

  • Trigger automation workflows for personalized omni-channel campaigns.

  • Integrate with CRM platform via webhooks to update customer data.

  • Back up content daily using CRON to cloud storage.

Overall, webhooks and CRON open up powerful integration capabilities to extend headless Craft.

Pushes vs Pulls

When integrating external platforms with Craft CMS, there are two main approaches:

Push - Craft pushes content out to other systems via APIs and webhooks. This allows broadcasting content to various channels as it's published in Craft. Pull - External systems pull content from Craft periodically using the APIs. Useful for read-only aggregation of content on fixed schedules.

Some examples:


  • Send new products via API to ecommerce store

  • Publish new blog posts out to social media

  • Push webinar registrations to email system


  • Aggregate blog content to digital signage system nightly

  • Pull events and hero images into mobile apps daily

  • Scrape and index new website content daily into search engine

The push and pull approaches give flexibility based on the integration requirements.

Omnichannel Content Delivery

A major benefit of headless Craft CMS is omnichannel content delivery to any endpoint:

  • Websites - Tradition websites, WebApps, and PWAs

  • Mobile Apps - Native iOS, Android, React Native

  • Digital Displays - Digital signage, Kiosks, Billboards

  • Smart Devices - Smart speakers, Smart TVs, Wearables

  • IoT - Automotive, Appliances, Industrial systems

Headless Craft provides content portability to power these experiences. The same content can be surfaced across multiple touchpoints tailored to each device.

Craft CMS flexibility enables omni-channel personalization and automation when integrated headless.

Challenges with Headless Craft CMS

Adopting a headless architecture with Craft CMS does introduce some unique challenges to consider:

Increased Complexity

Headless CMS adds layers of complexity compared to traditional monolithic CMS platforms. There are more moving parts to coordinate:

  • APIs need to be designed, built and maintained

  • Content workflows need optimization

  • Integrations must be managed

  • Custom front-ends developed

  • Deployments and hosting environments expanded

This can introduce development challenges and overhead costs that require planning. Failing to handle the added complexity will undermine headless benefits.

Reliance on APIs

With headless CMS, the availability and performance of the content APIs become critical. Any API downtime or degradation severely impacts the front-end.

Strategies to minimize API risk:

  • Redundant API gateways and caching layers

  • Rigorous API monitoring and alerting

  • Load testing and capacity planning

  • Backup APIs or fallback content plans

Careful API planning is required to reduce reliance risks.

Headless Expertise Required

Headless CMS requires specialized skills across the stack:

  • API development and management

  • Front-end/JS frameworks like React

  • Infrastructure for deployment, scaling, resiliency

  • Automation skills for CI/CD

  • Integration architecture

  • Security best practices

Lacking these skills will hinder headless execution. Many traditional CMS teams may need upskilling or outside expertise.

A headless architecture does require mitigating the challenges of complexity, reliability, and specialized skills. With proper planning, these can be overcome to realize headless benefits.

Shape April 2022 HR 202
Andy Golpys
- Author

Andy has scaled multiple businesses and is a big believer in Craft CMS as a tool that benefits both Designer, Developer and Client. 

Show us some love
Email Us
We usually reply within 72 hours
Agency Directory
Submit your agency
Affiliate Partners
Let's chat