DocumentationAEM as a Cloud ServiceUser Guide

Best Practices for the setup and use of AEM GraphQL with Content Fragments

Last update: June 21, 2024
  • Topics:
  • Headless

CREATED FOR:

  • Admin
  • Developer

These guidelines summarize the recommended best practices for setting up, configuring and using AEM with GraphQL and Content Fragments.

Getting Started

To help get you up to speed:

  • What is Headless?
  • An overview of the various environments in the AEM Architecture

Setup

To securely setup AEM GraphQL for use with Content Fragments and your apps you need to configure various components.

GraphQL endpoint creation (including security)

The endpoint is the path used to access GraphQL for AEM. These endpoints need to be created, and published, so that they can be accessed securely.

Details

Manage GraphQL endpoints in AEM

Environments

Endpoints need to be configured in:

  • Author
  • Preview
  • Publish

For:

  • Development
  • Testing
  • Production

AEM Dispatcher caching

NOTE
If caching in the Dispatcher is enabled then the CORS setup is not needed, and so can be ignored.

Caching of persisted queries is not enabled by default in the Dispatcher. Default enablement is not possible as customers using CORS (Cross-Origin Resource Sharing) with multiple origins need to review, and possibly update, their Dispatcher configuration.

Details

GraphQL Persisted Queries - enabling caching in the Dispatcher

Environments

The Dispatcher is usually configured for:

  • Publish: production

CORS setup

NOTE
If caching in the AEM Dispatcher is enabled then the CORS setup is not needed, and so this section can be ignored.

To access the GraphQL endpoint, a CORS policy must be configured and added to an AEM Project that is deployed to AEM via Cloud Manager. This is done by adding an appropriate OSGi CORS configuration file for the desired endpoint(s).

Details

Cross-Origin Resource Sharing (CORS) configuration

Environments

CORS is usually configured for:

  • Publish: production

Authentication

A primary use case for The Adobe Experience Manager as a Cloud Service (AEM) GraphQL API for Content Fragment Delivery is to accept remote queries from third-party applications or services. These remote queries may require authenticated API access to secure headless content delivery.

Details

Authentication for Remote AEM GraphQL Queries on Content Fragments

Environments

Authentication is usually configured for:

  • Preview
  • Publish

For:

  • Development
  • Testing
  • Production

Permissions

With a headless implementation, there are several areas of security and permissions that should be addressed. Permissions and personas can broadly be considered based on the AEM environment Author or Publish. Each environment contains different personas and with different needs.

Details

Permission considerations for headless content

Environments

Permissions are usually configured for:

  • Author
  • Preview
  • Publish

For:

  • Development
  • Testing
  • Production

Use a Content Delivery Network (CDN)

GraphQL queries and their JSON responses can be cached if targeted as GET requests when using a CDN. In contrast, uncached requests can be very (resource) expensive and slow to process, with the potential for further detrimental effects on the origin’s resources.

Details

CDN in AEM as a Cloud Service

Environments

A CDN is usually configured for:

  • Publish: production

Configure and create Content Fragments

AEM GraphQL is used to retrieve information from your Content Fragments. These need to be configured, then a structure and location defined, before you can create the content.

Details

  • Create a Configuration
  • Create a Content Fragment Model
  • Create an Assets Folder
  • Create, and edit, your Content Fragments

Environments

Content Fragments are defined, authored, tested, published, and accessed on:

  • Author
  • Preview
  • Publish

For:

  • Development
  • Testing
  • Production

Using AEM GraphQL

Optimize your GraphQL queries

These guidelines are provided to help prevent performance issues with your GraphQL queries.

Details

Optimizing GraphQL Queries

NOTE
The optimization guidelines cover cache configuration, already covered in Setup.

Access GraphQL from your apps

AEM headless CMS gives developers the freedom to build and deliver exceptional experiences using the languages, frameworks, and tools they’re already familiar with.

Details

  • Install, and use, the AEM SDK for development
  • AEM Headless Developer Resources
  • Examples, including React, Next.js, Node.js, among others

Environments

Apps are usually developed, tested, and used on:

  • Preview
  • Publish

For:

  • Development
  • Testing
  • Production

Additional Resources

For more details about AEM GraphQL and Content Fragments, see the following:

  • AEM GraphQL API for use with Content Fragments
  • Using the GraphiQL IDE
  • AEM Headless Developer Resources
recommendation-more-help
fbcff2a9-b6fe-4574-b04a-21e75df764ab