In this part of the AEM Headless Developer Journey, learn about what is required to get your own project started with AEM Headless.
In the previous document of the AEM headless journey, Learn About CMS Headless Development you learned the basic theory of what a headless CMS is and you should now:
This article builds on those fundamentals so you understand how you can use AEM to implement a headless solution.
This document helps you understand AEM Headless in the context of your own project. After reading you should:
Before you can define your headless project within AEM, it is important to understand some basic AEM concepts.
At its simplest, AEM consists of an author instance and a publish instance which work together to create, manage, and publish your content.
Content begins on the author instance. This is where content authors create their content. The author environment offers various tools for authors to create, organize, and reuse their content.
Once content is created in the author instance, it must be published to be available to other services to consume. A publish instance contains all content that has been published.
Prior to publishing to the Publish instance you can also publish your Content Fragment to the Preview Service for testing and reviewing. This is done from the Content Fragments console.
Replication is the act of transferring content from the author instance to the publish instance. This is done automatically by AEM when an author or other user with appropriate rights publishes content.
At its simplest level, creating digital experiences in AEM requires the following steps:
AEM Headless builds off this technical foundation by offering powerful tools to manage headless content which is described in the next section.
The headless capabilities of AEM are based on a few key features. These are explained in detail in later parts of the journey. It is important now only to know the basics of what they do and what they are called.
Content Fragment Models define the structure of the data and content that you create and manage in AEM. They serve as a kind of scaffolding for your content. When choosing to create content, your authors select from the Content Fragment Models you define, which guides them in creating content.
Content Fragments allow you to design, create, curate, and publish page-independent content. They allow you to prepare content ready for use in multiple locations and over multiple channels.
Content fragments contain structured content and can be delivered in JSON format.
To modify your content headlessly, AEM offers two robust APIs.
You will learn about these APIs and how to use them in a later part of the AEM headless journey. Or see additional resources section below for additional documentation.
AEM supports both the full headless and the traditional full stack or headful models of a CMS. However AEM offers not only these two exclusive choices, but the ability to support hybrid models that combine the advantages of both, offering unique flexibility for your headless project.
To ensure your understanding of headless concepts, this AEM Headless Developer Journey focuses on the pure headless model to get you up-and-running as soon as possible with no coding in AEM.
However you should be aware of the additional hybrid possibilities open to you once you understand AEM’s headless features. These cases are laid out below for your awareness. At the end of the journey, you are introduced to these concepts in more detail in case such flexibility is required for your project.
Let us assume that your basic requirement is at a minimum to deliver content from AEM to an existing, external service.
This level of integration is the traditional headless model and allows your content authors to create content in AEM and deliver it heedlessly to any number of external services using GraphQL or to edit them from external services using the Assets API. No coding is required in AEM.
In this model, AEM is only used for creating and serving the content by using AEM Content Fragments. Rendering and interaction with the content is delegated to the consuming external application, often a single-page application (SPA).
This level of integration builds on the first level, but also allows the external application (SPA) to be embedded in AEM so that the content authors can view the content in the context of the external application within AEM. The application can also support limited editing of the external application within AEM.
This level has the advantage of allowing content authors to flexibly author content in AEM in a headful way, with their content presented in-context with an embedded external SPA, while still delivering the content headlessly.
This level of integration builds on level two by enabling most content in the external SPA to be editable within AEM.
If your goal is to create a new SPA that headlessly consumes content from AEM, you can use features such as Content Fragments to manage your headless content, and also build a SPA with AEM’s SPA Editor framework.
Using the SPA Editor, the SPA not only consumes content from AEM, but is also fully editable within AEM by your content authors giving you both the flexibility of headless delivery and in-context editing within AEM.
There are a number of requirements before you begin your headless AEM project.
For any successful project, it is important to clearly define not only the requirements of the project, but also the roles and responsibilities.
It is important to have a clearly defined scope for the project. Scope informs acceptance criteria and lets you establish a definition of done.
The first question you must ask is “What am I trying to achieve with AEM Headless?” The answer should in general be that you have or will have in the future an experience application that you have built with your own development tools not with AEM. This experience application could be a mobile app, a web site, or any other end-user customer facing experience application. The goal for using AEM Headless is to feed your experience application with content that is created, stored, and managed in AEM with state-of-the-art APIs that would call AEM Headless to fetch content or even fully CRUD content directly from your experience application. If this is not what you are looking to do, you probably want to go back to the AEM documentation and find the section that better suits what you want to accomplish.
The roles for any individual project vary, but important ones to consider in the content of AEM headless development are:
The administrator is responsible for the base setup and configuration of your system. For example, the administrator sets up your organization within the Adobe user management system, referred to Identity Management System (IMS). The administrator is the first user from the organization to receive an email invitation from Adobe once your organization has been created by Adobe within IMS. The administrator has the ability to login to IMS and add users of other personas.
Once the users are configured by the administrator, they are be granted the permissions to access all the AEM resources to accomplish their work as contributors to delivering the experience application using AEM Headless.
The administrator should be the user who sets up AEM and prepares the runtime environment to enable content authors to create and update content and developers to use APIs that fetch or modify content for their experience applications.
Content authors create and manage the content that is delivered headlessly by AEM. Content authors use AEM features such as Content Fragment editor and various consoles to manage their content.
Content authors should keep in mind the following best practices.
Plan for translation at the very beginning of the project. Consider “Translation Specialist” as a separate persona whose responsibility it is to define what content should be translated and what should not be, and what translated content may be modified by regional or local content producers.
Create a plan on what content translation you need.
Be clear about your content update workflow. What is the approval process that the system must support? Might AEM workflows be used to automate this process?
Note that your content hierarchy can be used to make translation easier.
See the additional resources section for additional documentation on AEM workflows and translation tools including links to the AEM Headless Translation Journey.
Folder hierarchy can address two major concerns with regards to content management:
AEM allows for a flexible content structure and a hierarchy can be arbitrarily large. However it is important to realize that any changes in folder structure may have unintended consequences for existing queries that rely on the content path. Therefore a well-defined hierarchy that is clearly set out in advance, can be helpful to your content authors.
Folders can also be restricted to only allow certain types of content (based on Content Fragment Models). It is recommended to always explicitly specify which models are allowed for all folders in the hierarchy. Specifying allowed content for a given folder:
By creating an appropriate content structure, it becomes easier to coordinate headless content authoring across channels so you can maximize content reuse. Leveraging content across multiple channels greatly improves content production efficiency and change management.
Content Fragment names must be descriptive for content authors. AEM transparently handles escaping and/or truncating the names used IDs at the repository level. Therefore the logical names provided by the content authors should always be readable and represent the contents.
Call To Action Button
See the additional resources section for additional documentation on AEM page naming conventions.
Content Fragments are used in AEM to create headless content. AEM supports up to ten levels of content nesting for Content Fragments. However it is important to keep in mind that AEM must iteratively resolve each reference defined in the parent Content Fragment, then check if there are any child references in all siblings. These operations can add up quickly and become a performance concern.
As a general rule-of-thumb, Content Fragment references should not be nested beyond five levels.
Content architects analyze the requirements for the data that must be delivered headlessly and defines the structure for this data. These structures are called Content Fragment Models in AEM. Content Fragment Models are used as the basis for the Content Fragments that the content authors create.
A useful approach when defining Content Fragment Models, is to create models that map to the UX components of the applications that consume the content.
Because the content authors interact with the models on a continual basis as they create new content, aligning the models to the UX helps them to visualize the resulting digital experience. Taking this alignment a step further, you can assign icons to the Content Fragment Models that represent the UX element so the authors can intuitively select the right model based on visual cues.
Developers are responsible for joining together the content being created headlessly in AEM to the consumer of that content, which can often be a single-page application (SPA), progressive web app (PWA), web shop, or other service external to AEM.
GraphQL serves as the “glue” between AEM and the consumers of headless content. GraphQL is the language that queries AEM for the necessary content.
Developers should keep in mind a few basic recommendations as they plan their queries:
ByPath) to retrieve Content Fragments.
select *-type queries that you might create in a relational database.
For a typical headless implementation using AEM, the developer requires no coding knowledge of AEM.
For any project to be a success, performance must be considered before any content is created.
You must understand your users/visitors expectations and design for those. Set service level objectives (SLOs) and measure them to understand if you meet your user’s expectations.
To understand traffic and traffic patterns start with gathering what you know from the past and then project to the expected growth over the next few years. Some of the most important variables to consider:
Often different sections of experiences have different frequencies of content updates. Understanding this is important to be able to fine-tune CDN and cache configurations. This is also important input for the Content Architects as they design models to represent your content. Consider:
Now that you have completed this part of the AEM Headless Developer Journey, you should:
You should continue your AEM headless journey by next reviewing the document Path to Your First Experience Using AEM Headless where you will learn how to set up the necessary tools and how to begin thinking about modeling your data in AEM.
While it is recommended that you move on to the next part of the headless development journey by reviewing the document Path to Your First Experience Using AEM Headless, the following are some additional, optional resources that do a deeper dive on some concepts mentioned in this document, but they are not required to continue on the headless journey.