Mastering Adobe Composable Part 2/3: AEM Headless Tools

In the first installment of my Mastering Adobe Composable series, we explored the shift toward modular, flexible architectures in the modern enterprise and explained the first installment available architectural choices in AEM. But once you commit to a composable strategy, the next challenge is selecting the right tools to bridge the gap between your content repository and your diverse digital endpoints. Adobe Experience Manager (AEM) has evolved far beyond its "headful" roots, now offering a robust suite of headless capabilities designed to suit different developer workflows and business requirements. This second installment dives deep into the AEM Headless toolkit—from the visual agility of the Universal Editor and the structured precision of Content Fragments and GraphQL, to the high-performance delivery of Edge Delivery Services. Whether you are looking to build a pure headless application or a hybrid experience, this guide breaks down the "how" and "why" of each technical path.

On This Page:

• Universal Editor
• Content Fragments Model and Content Fragments
• AEM GraphQL APIs
• Content Services (Sling Model Exporter)
• AEM Delivery APIs
• Edge Delivery Services
• Comparing Headless Options

Let's dive in.

Universal Editor

The Universal Editor is a modern visual authoring tool in Adobe Experience Manager (AEM) Sites that empowers marketing teams to create impactful web experiences. It supports WYSIWYG editing for both headless and headful implementations, allowing authors to edit content directly within the preview experience. This eliminates the need to navigate separate content sources while providing instant visual feedback, making it easier to manage content fragments, page components, and layouts in a single, unified interface.

Built for flexibility and ease of use, the Universal Editor requires minimal training and automatically enforces corporate brand guidelines, enabling scalable content production across an organization. Authors can compose, reorder, nest, and style content blocks, preview changes across devices, and reuse content across multiple channels. Integration with AEM tools such as the Sites Console and the Content Fragment Editor ensures a seamless authoring experience. At the same time, extension points allow developers to customize workflows, blocks, and other UI elements to meet specific business needs.

Developers benefit from the Universal Editor’s versatility, as it supports virtually any web framework (including React, Next.js, Astro, Angular, and more), server-side or client-side rendering, and a range of hosting models. Its design as a true editor-as-a-service enables enterprise-grade visual editing for headless architectures without imposing constraints on existing implementations.

Compared to the Content Fragment Editor, which is optimized for creating reusable content without layout concerns, the Universal Editor allows marketing teams to develop content tailored to a specific layout, enhancing the visitor experience and enabling more engaging, context-driven interactions.

How it Works

The Universal Editor uses four components: Editors, Remote App, API Layer, and Persistence Layer. To edit content directly on the webpage, an instrumented DOM is needed. This involves adding metadata to the DOM, allowing the Universal Editor to communicate with the remote application implementation. Authors can then edit content directly within the web experience. Additionally, if components with properties can't be edited directly, such as carousel rotation times or accordion tab configurations, a form-based editor is accessible in the side rail.

The Universal Editor emphasizes a minimal SDK, placing the responsibility of instrumentation on the remote app implementation.

The API Layer is crucial in facilitating content data and persisting changes. Regardless of the source systems or consumption methods of content data, the API Layer ensures that required attributes are defined and provided for in-context editing. Furthermore, each editable data item is assigned a Uniform Resource Name (URN) identifier that directs the persistence process to the appropriate system and resource. The Persistence Layer handles content storage and supports various storage locations, including AEM, Magento, and others.

Finally, the content changes are dispatched to the Universal Editor Service, which operates on Adobe I/O Runtime. This service loads plugins from the Extension Registry based on provided URNs, facilitating communication with backend systems and ensuring a unified response to content modifications.

Advantages

• Leverage Other AEM Sites Features: Supports translations, MSM, launches, content reuse, and more, enabling efficient management of multilingual and multi-site content.

• Simplified Editing: Universal Editor provides an intuitive in-place editing interface, enabling you to edit content directly within the web experience.

• Enhanced Flexibility: With minimal training, authors can easily manage content within the web page's context, ensuring accurate representation to visitors and improving overall efficiency.

• Consistent Experience: The Universal Editor aims to provide a consistent editing experience across different content types, promoting coherence and uniformity in content management.

• It's included at no extra cost if you use AEM as a Cloud Service.

Disadvantages

• Limited Default Features: The UE ships with only essential features enabled by default, as allowing too many options can create unnecessary load and degrade the authoring experience.

• Maturing Technology: Although the UE is generally available, it is still relatively new and continues to evolve to reach full maturity.

Common Use Case

While the Universal Editor is most naturally leveraged in headless scenarios, Adobe recommends it as the default authoring experience for both headless and headful implementations.

Content Fragments Model and Content Fragments

Content Fragments Model

In AEM, a content fragment model (CFM) is a schema or data structure that organizes content fragments' content. It functions as a blueprint, defining the content type and structure of these fragments. Essentially, it's a template specifying the data each content fragment will contain and how it will be organized. This approach ensures consistent content presentation and simplifies content management, particularly when content must be flexible across devices and interfaces.

The Content Fragment Model offers a set of predefined data types for structuring data. These include:

• Single line text

• Multi-line text

• Number

• Boolean

• Date and time

• Enumeration (for checkboxes, radio buttons, or dropdowns)

• Tags

• Content References (for images or nested content)

• Fragment Reference (linking other content fragments)

• JSON Object (for additional information in JSON format)

• Tab Placeholder (for organizing content types into sections)

These data types cover most user needs, but custom data types can be created in AEM if necessary. Each data type also includes various configurations, such as required fields, validation rules, and placeholders, providing flexibility and robustness to the content structure.

Content Fragments

A content fragment is a versatile container for content, independent of design or presentation considerations. It can hold unstructured data, such as text and images, or structured data elements defined by a data model. Unstructured content fragments are suitable for lengthy texts, such as articles, enabling authors to focus solely on writing while downstream channels handle layout and formatting. On the other hand, structured content fragments are ideal for business-specific data. Authors can utilize a text summarization feature to create tailored variations optimized for different channels.

Stored within Adobe Experience Manager (AEM) Assets, content fragments benefit from version control, approval workflows, and translation services. Although content fragments are a feature of Sites, they are stored as Assets, enabling seamless integration into content management processes. With AEM as a Cloud Service, content fragments facilitate the design, creation, curation, and publication of page-independent content. This flexibility makes them well-suited for use across multiple locations and channels, particularly in headless delivery scenarios.

Access to content fragments is facilitated through two consoles: Content Fragments and Assets. The new Content Fragment editor, designed primarily for headless content delivery, offers customization options via App Builder.

Content fragment structures vary from basic to complex or nested, depending on the requirements. Basic structures typically feature simple fields, such as single or multi-line text, which are suitable for straightforward content preparation. Complex structures combine multiple fields of various data types, catering to more intricate content needs. Nested structures utilize reference data types to organize content hierarchically, a technique often employed in headless delivery scenarios.

Content fragments can be utilized as HTML via the AEM Core component "Content Fragment," allowing for the direct delivery of default content into HTML paragraphs. Alternatively, the sling exporter exposes content fragment data as JSON objects without business-layer abstractions, presenting it in its raw form. For headless delivery, it's recommended that content fragments be exposed via GraphQL for efficient integration into various applications and platforms.

Common Use Cases

• Leveraging GraphQL integration, content fragments enable seamless content delivery across platforms, empowering headless use cases.

• With support for structured data entry and form-based content creation, content fragments ensure consistency and organization in data management processes.

• Tailored for crafting long-form editorial content, content fragments accommodate multi-line elements, enabling comprehensive storytelling experiences.

• Content fragments are suited for managing content independently of its delivery channels. They offer efficient handling and distribution capabilities across various platforms.

Experience Fragments vs Content Fragments

Sometimes, these two options can be confused or overlooked. In the chart below, we can see their similarities and differences.

AEM GraphQL APIs

GraphQL is a query language for APIs and a runtime for executing these queries, making it a popular choice for headless use cases. With GraphQL, client applications can create queries tailored to retrieve only the data they need. In this scenario, a server hosts all content and exposes it through GraphQL APIs. Client applications, such as mobile, desktop, or IoT devices, can formulate GraphQL queries to access the content needed for their apps, and the GraphQL API returns the requested data.

The rise in GraphQL's popularity can be attributed to several key factors:

• Clients can craft queries to fetch specific properties they need, ensuring efficient data retrieval.

• GraphQL enables fetching multiple resources in a single request, thereby minimizing HTTP requests and improving application speed and performance. For instance, a single query could retrieve unrelated items, such as persons and countries.

• The GraphQL API is strongly typed, enforcing data model constraints and providing clear error messages and predictable results. Features like code completion further enhance query development.

• GraphQL is designed to adapt to evolving data structures, seamlessly exposing additional fields or properties as they are added.

AEM provides a set of GraphQL APIs to expose data about content fragments. Although it's an abstraction of the original GraphQL language, it sufficiently covers most use cases. All content fragments within AEM are accessible via these APIs. Applications can query for lists of content fragments based on models or request data about individual fragments based on their location in AEM.

Properties available for GraphQL queries are derived from content fragment models. Any changes to these models are automatically reflected in the GraphQL API. As GraphQL is strongly typed, queries can be validated against the content fragment model's data schema in advance.

In addition to the AEM GraphQL API, Adobe has introduced a new editor, the GraphiQL IDE. This editor enables developers to swiftly test and refine queries while providing seamless access to documentation. It simplifies the learning process by giving clear insights into available methods.

Persisted Queries

As mentioned earlier, GraphQL enables users to craft their own queries, which can quickly grow in size and complexity. To address this challenge, persistent queries were introduced. These persisted queries enable users to store the text of a GraphQL query on the server, specifically within AEM, rather than sending it with each request. Consequently, queries can be invoked using an ID rather than including the entire query in the request body.

Standard GraphQL queries are executed via POST requests, which pose issues because HTTP caches or CDNs cannot easily cache the responses. On the other hand, AEM persisted queries offer a solution by simplifying requests and enhancing security. By encapsulating queries on the server, AEM administrators retain complete control over them. Utilizing persisted queries is considered a best practice and highly recommended when working with the AEM GraphQL API.

Several methods exist for creating, updating, and executing persisted queries. These methods include using the GraphiQL IDE, cURL, or other tools such as Postman. However, the GraphiQL IDE is the preferred method for persisting queries.

Persisted Queries Best Practices

While Persisted Queries offer significant benefits for headless implementations, they are not a silver bullet. To ensure optimal functioning, adhering to certain best practices is essential. Here are some areas of key consideration:

• Reduce the initial result set to keep it as small as possible: In AEM instances with a high number of Content Fragments sharing the same model, GraphQL list queries can become resource-intensive. This occurs because all fragments that share a model in the GraphQL query must be loaded into memory, consuming both time and memory. Here are some ways to mitigate this issue:

  • Hybrid Filtering: This combines JCR and AEM filtering. It applies a JCR filter to reduce the result set before loading it into memory for AEM filtering, improving efficiency. Implementing Hybrid Filtering in AEM requires updating existing Content Fragments.

  • Pagination: The response time for complex queries with large result sets can be improved by segmenting responses into chunks, a standard feature of GraphQL. GraphQL in AEM supports both limit/offset-based and cursor-based pagination.

Note that filtering, which reduces the number of items in the final result set, can only occur after loading the entire set into memory. Consequently, even small result sets may cause poor performance. However, the actual slowness stems from handling the initial set's size internally before filtering can be applied.

• To enhance overall performance, persisted queries should be cached at both the Dispatcher and Content Delivery Network (CDN) layers. Manual configuration is required for the Dispatcher, and optimization can be achieved using time-to-live (TTL) headers. While AEM provides default TTL values per tier (author and publish), these can be customized at various levels: through the GraphiQL IDE, via cURL commands at the persisted query level, using Cloud Manager variables, or through OSGi configuration.

• Persisted queries should only be consumed from Publish instances. While they can be utilized for testing or development purposes on Author instances, data should not be directly consumed by them.

• Utilize a taxonomy for your content fragments to narrow the scope of the content to be processed. This is typically considered a best practice in AEM content management.

• Apply JCR filtering on top-level fields, combined with logical operators such as AND. This efficiently narrows down results, particularly when dealing with nested fragments. Avoid using OR expressions with nested fragments, as they cannot be optimized for query performance.

• Refrain from filtering on multi-line text fields like HTML, Markdown, plaintext, or JSON. These fields cannot be filtered via JCR queries, as their content is dynamically calculated. If filtering on a multiline text field is necessary, limit the initial result set size by combining additional filter expressions with the AND operator. Alternatively, consider restricting the scope by filtering on the _path field.

• Avoid filtering on virtual fields, which are calculated during GraphQL query execution and are not compatible with JCR-based filtering. These fields are usually identified by the usage of “_” at the start of their name.

• While nesting is useful for custom content structures, excessive levels can lead to longer processing times as GraphQL traverses nested fragments. To mitigate this, limit nesting to 5 or 6 levels, ensuring efficient querying and content management.

• Optimize JSON response size and query processing time, and avoid outputting all formats (Rich Text, Simple Text, and Markdown) for multi-line text elements in AEM GraphQL. Outputting all formats triples the JSON output size, leading to longer computation times, especially with large result sets.

• To ensure proper handling and consistency, modify Content Fragments and their resources exclusively through the AEM UI or APIs. To maintain integrity and prevent potential issues, avoid making direct modifications in JCR.

Content Services (Sling Model Exporter)

Content Services from Adobe introduced a Headless pattern to leverage AEM content for broader applications, marking one of Adobe's first initiatives towards a headless approach. They transcend traditional web page limitations, offering a generalized approach to describing and delivering content.

Technically, Content Services refers to the Apache Sling Model exporter framework, which is part of the Sling Models. Apache Sling is one of the foundational technologies in Adobe Experience Manager's technology stack.

The Sling Model Exporter was introduced in Apache Sling Models 1.3.0, providing an elegant way to export or serialize Sling Model objects into custom abstractions. This exporter automatically serializes Sling Model objects into JSON, enabling dual servicing of web requests. HTML responses are created using the traditional Sling Model request flow. At the same time, JSON renditions are exposed for consumption by web services or other channels, such as mobile apps, SPAs, and IoT devices.

This technology gained popularity when the AEM WCM Core components adopted it as a best practice, enabling them to expose their configurations and content as JSON out of the box. Another promotion of this technology was seen in the SPA editor, which relies on the Sling Model exporter to consume and build its technology.

How Does it Work?

In the above image, we can see how this works:

1. An HTTP GET request is made for a resource in AEM, specifying the selector and extension registered with the Sling Model’s Exporter. For example, HTTP GET /content/my-resource.model.json.

2. Sling resolves the requested resource’s sling:resourceType, selector, and extension to a dynamically generated Sling Exporter Servlet, mapped to the Sling Model with Exporter.

3. The resolved Sling Exporter Servlet invokes the Sling Model Exporter against the Sling Model object, which is adapted from the request or resource determined by the Sling Model's adaptables.

4. The exporter serializes the Sling Model based on the Exporter Options and Exporter-specific Sling Model annotations, then returns the result to the Sling Exporter Servlet.

5. Finally, the Sling Exporter Servlet returns the JSON rendition of the Sling Model in the HTTP Response.

Common Use Cases

• SPA implementations with SPA Editor (Deprecated). The Sling Model Exporter is the core of the SPA Editor, and it operates in a hybrid manner. Any custom component developed for a SPA implementation must implement the Component Exporter interface, which utilizes the Sling Model Exporter framework under the hood.

• If content has already been built and needs to be reused across several channels, the Sling model exporter is usually the easiest way to expose it in JSON format. If the content is built following best practices, this should be easy to achieve.

• Adding extra business rules to the exposed data. An advantage of the Sling Model Exporter is its native capability to refine data before exposure. Using plain Java objects (POJOs) within the Sling Model framework, users can manipulate and enhance data as needed. This flexibility enables selective exposure, data transformation, and augmentation, providing greater control over the final output.

AEM Delivery APIs

In addition to leveraging the Sling Model exporter, Adobe has shifted its focus to provide more out-of-the-box tools for headless implementation. With this in mind, Adobe has been and continues to work on APIs to expose content as JSON, following the OpenAI specification.

The provision of APIs isn’t a pattern unique to AEM. However, it is prevalent across various Adobe products within the Adobe Creative Cloud (including Photoshop and Illustrator), Adobe Experience Platform (AEP), Adobe Document Cloud (such as PDF services and Acrobat Sign), and Adobe Experience Cloud (including AEM, Target, and Analytics). All of these products offer APIs that enable headless interaction, enabling Adobe products to integrate more flexibly with third-party systems.

In this section, we will briefly discuss APIs that are relevant to Adobe Experience Manager.

Assets API

The Assets HTTP API provides CRUD operations for digital assets, metadata, renditions, and comments. It also supports structured content through Content Fragments. This API is accessible at /api/assets.json and supports Content Fragments.

The Assets HTTP API includes the following features:

• Retrieve a folder listing

• Create a folder

• Update asset metadata

• Create an asset rendition

• Update an asset rendition

• Create an asset comment

• Copy a folder or asset

• Move a folder or asset

• Delete a folder, asset, or rendition

In addition to these functionalities, initially, the Assets API also supported limited interaction with Content Fragments, allowing the following actions:

• Retrieve a content fragment by its path

• Create a new content fragment

• Update the content fragment

• Update content fragment’s variations

• Delete content fragments

Content Fragments API

Adobe introduced a new API in 2024 to enable comprehensive interaction with Content Fragments and their models. This API provides a range of examples, extensive documentation, and a playground for testing with real data directly from your server, requiring minimal configuration. Some of the operations supported by this new API include:

• Fragment Management (CRUD operations and more upon CFs)

• Fragment Variations (CRUD operations and more upon CF variations)

• Fragment Versioning (CRUD operations and more upon CFs versions)

• Model Management, for interacting with Content Fragment Models

• Search, a Search API for Content Fragments based on various Search Criteria.

• Tagging, for interacting with the Tags applied to a Content Fragment Model

• References

• Translations

• Permission to get a list of permissions the user has over a list of Folders, Content Fragments, or Content Fragment Models

• Launch workflows related to Content Fragments

• Trigger content fragment and content fragment model events (Adobe Events) for other applications subscribed to them.

Common Use Cases

• Integration with Third-Party Systems: REST APIs enable seamless integration with external systems, facilitating data exchange and communication between applications or services.

• IoT (Internet of Things) Integration: REST APIs play a crucial role in IoT ecosystems, facilitating communication between IoT devices and central servers to transmit data, receive commands, and perform actions based on predefined rules.

• Microservices Architecture: REST APIs are foundational in microservices-based architectures, enabling independent services to communicate with each other using standard HTTP methods, thereby promoting modularity, scalability, and flexibility in software design.

Edge Delivery Services

Edge Delivery Services (EDS) is the latest offering from Adobe, comprising a suite of composable services designed to enhance Adobe Experience Manager (AEM) capabilities and introduce a fresh approach to content creation. The primary goal of Edge Delivery Services is to:

• Create sites with a perfect Lighthouse score.

• Utilize a built-in experimentation framework that enables the rapid creation of tests.

• Decoupling content sources increases authoring efficiency. In EDS, you can select the authoring experience that best suits your needs, including the Universal Editor, Document Authoring, or document-based authoring (e.g., Google or SharePoint).

Edge Delivery Services offers an effortless, intuitive way to create "headless" content. Users can utilize spreadsheets for a document-based authoring experience or select a dedicated template for the traditional AEM Authoring experience.

Spreadsheet in Document-based Authoring

When opting for document-based authoring, Edge Delivery Services extracts content from Google Docs or SharePoint spreadsheets, simplifying the creation of accessible JSON-formatted content. Configuration is straightforward: users create a spreadsheet and add a table with the data to be exposed. Once published, the data becomes accessible through a .json endpoint.

Spreadsheet Template in Traditional AEM Authoring

Similar to document-based authoring, the AEM Authoring experience exposes data in JSON format, presented in a table format. AEM includes a dedicated template, "Spreadsheet," for this purpose. This template mimics a spreadsheet, enabling authors to input raw data in table format. A mapping configuration must be established after creating and publishing the data in table format. This configuration specifies the endpoint name and source, facilitating access to the data in JSON format.

Advantages

• An easy way to expose data as an endpoint or in a headless manner.

• No learning curve is required due to the native table format used.

• Pagination is implemented out of the box, as the JSON data includes the necessary parameters and information to support it.

• The Document-based spreadsheet allows multiple sheets, enabling the quick creation of variations of the endpoint.

Disadvantages

• It does not support native Arrays as cell values, so if used, they are delivered as strings.

Comparing Headless Options

In the final article in our series, we'll explore the tools and technologies available that enable AEM headless implementations.

Oshyn Can Help

If you need help navigating the headless tools for AEM, our team is ready to assist. Simply schedule a time or contact us to arrange a conversation with one of our expert consultants.