Using Sulu's Headless API to Decouple Frontends While Keeping the Admin UI

The problem: Twig‑coupled content limits frontend flexibility

Many Sulu projects start with Twig templates because they integrate tightly with the CMS’s admin interface. When the same content must also be consumed by a React, Vue, or mobile app, developers face a choice: duplicate the content logic in a custom API or force the frontend to render Twig‑generated HTML. Both approaches add maintenance overhead and can create inconsistencies between the editing experience and the delivered experience.

Thesis: Sulu’s built‑in Headless API lets you expose structured JSON without losing the admin UI

By installing the SuluHeadlessBundle and configuring a few YAML files, Sulu can serve the same content as JSON via RESTful endpoints. Editors continue to use the familiar Sulu admin, while frontend teams retrieve plain data and render it in any technology stack.

1. Install and enable the bundle

Run Composer in the project root (you need write access to the composer.json file and permission to execute Composer commands):

composer require sulu/sulu-headless-bundle

After installation, add the bundle to config/bundles.php if it is not added automatically:
return [
    // …
    Sulu\Bundle\HeadlessBundle\SuluHeadlessBundle::class => ['all' => true],
];

2. Configure the API gateway
Create config/packages/sulu_headless.yaml (or edit the existing file) to define which content types and locales are exposed:
sulu_headless:
    api:
        schema:
            # Expose the Article document type for all locales
            App\Document\ArticleDocument:
                locales: [en, de]
                # Optionally limit fields
                fields: [title, author, body, seoTitle, seoDescription]
        # Enable the REST entrypoint under /api
        entrypoint: /api

Clear the cache to load the new configuration:
php bin/console cache:clear --env=prod

3. Worked example: fetching a blog article
Assuming an Article document with ID 123 exists, a GET request to the Headless endpoint returns JSON:
curl -X GET "http://localhost:8000/api/articles/123" \
     -H "Accept: application/json"

Expected response (fields match the schema defined above):
{
    "id": 123,
    "title": "Introducing Sulu’s Headless API",
    "author": "Jane Doe",
    "body": "
Sulu now offers a …
",
    "seoTitle": "Sulu Headless API | Docs",
    "seoDescription": "Learn how to expose Sulu content as JSON."
}

The frontend can parse this JSON and render it using React, Vue, or any other framework. Editors still edit the article in /admin and see the same fields.
Trade‑off and limitation: presentation logic must be re‑implemented
The Headless API does not render Twig templates. Any logic that lived in Twig — such as custom filters, image transformations, or component inclusions — must be recreated in the frontend consuming the JSON. Additionally, when you upgrade Sulu, the API schema may change (new fields, renamed properties, or removed locales). You should treat the /api/_schema endpoint as a contract and run schema‑validation tests as part of your CI pipeline.
Actionable closing: validate on staging, then migrate incrementally

    
Deploy the bundle to a staging environment that mirrors production.
    
Verify the schema: curl http://staging.example.com/api/_schema and confirm that the expected document types appear.
    
Test a few representative endpoints with curl or Postman and check that the JSON matches the schema and contains no unintended fields.
    
Pick a low‑risk frontend module (e.g., a blog list) and switch it to consume the JSON endpoint while keeping the rest of the site on Twig.
    
Monitor for missing fields or formatting issues; adjust the frontend or the API schema configuration as needed.
    
Gradually migrate more modules, retiring Twig‑only rendering where the Headless API provides sufficient data.

By following these steps, you gain the flexibility of a decoupled frontend without sacrificing the editing experience that makes Sulu attractive to content teams.