Getting Started with AEM Headless getting-started

In this part of the AEM Headless Developer Journey, learn about what is required to get your own project started with AEM Headless.

The Story So Far story-so-far

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.

Objective objective

This document helps you understand AEM Headless in the context of your own project. After reading you should:

AEM Basics aem-basics

Before you can define your headless project within AEM, it is important to understand some basic AEM concepts.

Author Instance author

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.

Publish Instance publish

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.

Replication replication

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.

AEM Basics Summary aem-basics-summary

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.

AEM Headless Basics aem-headless-basics

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 content-fragment-models

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 content-fragments

Content Fragments let you design, create, curate, and publish page-independent content. They let you prepare content ready for use in multiple locations and over multiple channels.

Content fragments contain structured content and can be delivered in JSON format.

GraphQL and REST APIs apis

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 the additional resources section below for additional documentation.

Headless Integration Levels integration-levels

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 will be introduced to these concepts in more detail in case such flexibility is required for your project.

You already have an external consume of headless content such as a singe page application (SPA). already-have-a-spa

Let us assume that your basic requirement is at a minimum to deliver content from AEM to an existing, external service.

Level 1: Content Fragment Integration - Traditional Headless Model level-1

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).

Level 2: Embed the SPA in AEM - Hybrid Model level-2

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.

Level 3: Embed and Fully Enable SPA in AEM - Hybrid Model level-3

This level of integration builds on level two by enabling most content in the external SPA to be editable within AEM.

You do not yet have an external consumer of the headless content such as a single page application (SPA). do-not-have-a-spa

If your goal is to create a 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.

Requirements and Prerequisites requirements-prerequisites

There are several requirements before you begin your headless AEM project.

Knowledge knowledge

Tools tools

Defining Your Project defining-your-project

For any successful project, it is important to clearly define not only the requirements of the project, but also the roles and responsibilities.

Scope scope

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’ve 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.

Roles and Responsibilities roles-responsibilities

The roles for any individual project vary, but important ones to consider in the content of AEM headless development are:

Administrator administrator

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 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 Author content-author

Content authors create and manage the content that is delivered headlessly by AEM. Content authors use AEM features such as Content Fragments and the Assets Console to manage their content.

Content authors should keep in mind the following best practices.

Plan for Translation translation

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.

Leverage the Content Hierarchy content-hierarchy

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 to maximize content reuse. Leveraging content across multiple channels greatly improves content production efficiency and change management.

Establish Good Naming Conventions naming-conventions

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.

See the additional resources section for additional documentation on AEM page naming conventions.

Do not Overextend Content Nesting content-nesting

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 Architect content-architect

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.

Developer developer

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:

For a typical headless implementation using AEM, the developer requires no coding knowledge of AEM.

Performance Requirements performance-requirements

For any project to be a success, performance must be considered before any content is created.

Be sure you 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.

Traffic Patterns traffic-patterns

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:

Update Frequency update-frequency

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:

What’s Next what-is-next

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.

Additional Resources additional-resources

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.