AEM GraphQL API for use with Content Fragments graphql-api-for-use-with-content-fragments

Learn how to use Content Fragments in Adobe Experience Manager (AEM) with the AEM GraphQL API for headless content delivery.

AEM GraphQL API used with Content Fragments is heavily based on the standard, open-source GraphQL API.

Using the GraphQL API in AEM enables the efficient delivery of Content Fragments to JavaScript clients in headless CMS implementations:

Prerequisites prerequisites

Customers using GraphQL should install the AEM Content Fragment with GraphQL Index Package 1.0.5. See the Release Notes for further details.

The GraphQL API graphql-api

GraphQL is:

For further information about the GraphQL API, see the following sections (among many other resources):

The GraphQL for AEM implementation is based on the standard GraphQL Java™ Library. See:

GraphQL Terminology graphql-terminology

GraphQL uses the following:

See the (GraphQL.org) Introduction to GraphQL for comprehensive details, including the Best Practices.

GraphQL Query Types graphql-query-types

With GraphQL you can perform queries to return either:

AEM provides capabilities to convert queries (both types) to Persisted Queries that are cached by Dispatcher and the CDN.

GraphQL Query Best Practices (Dispatcher and CDN) graphql-query-best-practices

Persisted queries are the recommended method to be used on publish instances as:

GraphQL queries using POST requests are not recommended as they are not cached, so on a default instance the Dispatcher is configured to block such queries.

While GraphQL also supports GET requests, these requests can hit limits (for example, the length of the URL) that can be avoided using persisted queries.

See Enable caching of persisted queries for further details.

GraphiQL Interface graphiql-interface

An implementation of the standard GraphiQL interface is available for use with AEM GraphQL.

This interface lets you directly input, and test, queries.

For example:

It provides features such as syntax-highlighting, auto-complete, auto-suggest, together with a history and online documentation:

Use Cases for Author and Publish Environments use-cases-author-publish-environments

The use cases can depend on the type of AEM environment:

Permissions permission

The permissions are required for accessing Assets.

GraphQL queries are run with the permission of the AEM user of the underlying request. If the user does not have read access to some fragments (stored as Assets), they do not become part of the result set.

Also, the user must have access to a GraphQL endpoint to be able to run GraphQL queries.

Schema Generation schema-generation

GraphQL is a typed API, which means that data must be clearly structured and organized by type.

The GraphQL specification provides a series of guidelines on how to create a robust API for interrogating data on a certain instance. To complete these guidelines, a client must fetch the Schema, which contains all the types necessary for a query.

For Content Fragments, the GraphQL schemas (structure and types) are based on Enabled Content Fragment Models and their data types.

For example, if a user created a Content Fragment Model called Article, then AEM generates a GraphQL type ArticleModel. The fields within this type correspond to the fields and data types defined in the model. In addition, it creates some entrypoints for the queries that operate on this type, such as articleByPath or articleList.

In GraphQL for AEM, the schema is flexible. This flexibility means that it is auto-generated each time a Content Fragment Model is created, updated, or deleted. The data schema caches are also refreshed when you update a Content Fragment Model.

The Sites GraphQL service listens (in the background) for any modifications made to a Content Fragment Model. When updates are detected, only that part of the schema is regenerated. This optimization saves time and provides stability.

So for example, if you:

The schema is served through the same endpoint as the GraphQL queries, with the client handling the fact that the schema is called with the extension GQLschema. For example, performing a simple GET request on /content/cq:graphql/global/endpoint.GQLschema results in the output of the schema with the Content-type: text/x-graphql-schema;charset=iso-8859-1.

Schema Generation - Unpublished Models schema-generation-unpublished-models

When Content Fragments are nested it can happen that a parent Content Fragment Model is published, but a referenced model is not.

When such happens, AEM generates an incomplete Schema for the parent Content Fragment Model. It means that the Fragment Reference, which depends on the unpublished model, is removed from the schema.

Fields fields

Within the schema, there are individual fields, of two basic categories:

Data Types data-types

GraphQL for AEM supports a list of types. All the supported Content Fragment Model Data Types and the corresponding GraphQL types are represented:

Helper Fields helper-fields

In addition to the data types for user-generated fields, GraphQL for AEM also generates several helper fields to help identify a Content Fragment, or to provide additional information about a Content Fragment.

These helper fields are marked with a preceding _ to distinguish between what has been defined by the user and what has been auto-generated.

Path path

The path field is used as an identifier in AEM GraphQL. It represents the path of the Content Fragment asset inside the AEM repository. This path is chosen as the identifier of a content fragment, because it:

The following code displays the paths of all Content Fragments that were created based on the Content Fragment Model Person.

{
  personList {
    items {
      _path
    }
  }
}

To retrieve a single Content Fragment of a specific type, you must also determine its path first. For example:

{
  authorByPath(_path: "/content/dam/path/to/fragment/john-doe") {
    item {
      _path
      firstName
      name
    }
  }
}

See Sample Query - A Single Specific City Fragment.

Metadata metadata

Through GraphQL, AEM also exposes the metadata of a Content Fragment. Metadata is the information that describes a content fragment, such as the following:

Because Metadata is generated through the Schema Editor and as such does not have a specific structure, the TypedMetaData GraphQL type was implemented to expose the metadata of a Content Fragment. The TypedMetaData exposes the information grouped by the following scalar types:

Each scalar type represents either a single name-value pair or an array of name-value pairs, where the value of that pair is of the type it was grouped in.

For example, if you want to retrieve the title of a Content Fragment, this property is a String property, so you would query for all the String Metadata:

To query for metadata:

{
  personByPath(_path: "/content/dam/path/to/fragment/john-doe") {
    item {
      _path
      _metadata {
        stringMetadata {
          name
          value
        }
      }
    }
  }
}

You can view all the metadata GraphQL types if you view the Generated GraphQL schema. All model types have the same TypedMetaData.

See Sample Query for Metadata - List the Metadata for Awards titled GB.

Variations variations

The _variations field has been implemented to simplify querying the variations that a Content Fragment has. For example:

{
  personByPath(_path: "/content/dam/path/to/fragment/john-doe") {
    item {
      _variations
    }
  }
}

See Sample Query - All Cities with a Named Variation.

GraphQL Variables graphql-variables

GraphQL permits variables to be placed in the query. For more information, see GraphQL documentation for Variables.

For example, to get all Content Fragments of type Article that have a specific variation, you can specify the variable variation in GraphiQL.

### query
query GetArticlesByVariation($variation: String!) {
    articleList(variation: $variation) {
        items {
            _path
            author
            _variations
        }
    }
}

### in query variables
{
    "variation": "uk"
}

GraphQL Directives graphql-directives

In GraphQL, there is a possibility to change the query based on variables, called GraphQL Directives.

For example, there you can include the adventurePrice field in a query for all the AdventureModels, based on a variable includePrice.

### query
query GetAdventureByType($includePrice: Boolean!) {
  adventureList {
    items {
      adventureTitle
      adventurePrice @include(if: $includePrice)
    }
  }
}

### in query variables
{
    "includePrice": true
}

Filtering filtering

You can also use filtering in your GraphQL queries to return specific data.

Filtering uses a syntax based on logical operators and expressions.

The most atomic part is a single expression that can be applied to the content of a certain field. It compares the content of the field with a given constant value.

For example, the following expression would compare the content of the field with the value some text, and succeed if the content equals the value. Otherwise, the expression fails.:

{
  value: "some text"
  _op: EQUALS
}

The following operators can be used to compare fields to a certain value:

Some types also let you specify additional options that modify how an expression is evaluated:

Expressions can be combined to a set with the help of a logical operator (_logOp):

Each field can be filtered by its own set of expressions. The expression sets of all fields mentioned in the filter argument are eventually combined by its own logical operator.

A filter definition (passed as the filter argument to a query) contains:

You can omit _logOp if you want to combine items with AND and _operator if you want to check for equality, because these values are defaults.

The following example demonstrates a full query that filters all persons that have a lastName of Provo or containing sjö, independent of the case:

{
  authorList(filter: {
    lastname: {
      _logOp: OR
      _expressions: [
        {
          value: "sjö",
          _operator: CONTAINS,
          _ignoreCase: true
        },
        {
          value: "Provo"
        }
      ]
    }
  }) {
    items {
      lastName
      firstName
    }
  }
}

When executing a GraphQL query using optional variables, if a specific value is not provided for the optional variable, then the variable will be ignored in the filter evaluation. This means, query results will contain all values, both null and not null, for the property related to the filter variable.

For example, in the query below, where no value is specified for the property lastName:

query getAuthorsFilteredByLastName($authorLastName: String) {
  authorList(filter:
    {
      lastName: {_expressions: {value: $authorLastName}
      }}) {
    items {
      lastName
    }
  }
}

All authors will be returned:

{
  "data": {
    "authorList": {
      "items": [
        {
          "lastName": "Hammer"
        },
        {
          "lastName": "Provo"
        },
        {
          "lastName": "Wester"
        },
        {
          "lastName": null
        },
         ...
      ]
    }
  }
}

While you can also filter on nested fields, it is not recommended, as it might lead to performance issues.

For further examples, see:

Sorting sorting

This feature lets you sort the query results according to a specified field.

The sorting criteria:

For example:

query {
  authorList(sort: "lastName, firstName") {
    items {
      firstName
      lastName
    }
  }
}

And also:

{
  authorList(sort: "lastName DESC, firstName DESC") {
    items {
        lastName
        firstName
    }
  }
}

You can also sort on a field within a nested fragment, using the format of nestedFragmentname.fieldname.

For example:

query {
  articleList(sort: "authorFragment.lastName")  {
    items {
      title
      authorFragment {
        firstName
        lastName
        birthDay
      }
      slug
    }
  }
}

Paging paging

This feature lets you perform paging on query types that returns a list. Two methods are provided:

List query - offset and limit list-offset-limit

In a ...Listquery you can use offset and limit to return a specific subset of results:

For example, to output the page of results containing up to five articles, starting from the fifth article from the complete results list:

query {
   articleList(offset: 5, limit: 5) {
    items {
      authorFragment {
        lastName
        firstName
      }
    }
  }
}

Paginated query - first and after paginated-first-after

The ...Paginated query type reuses most of the ...List query type features (filtering, sorting), but instead of using offset/limit arguments, it uses the first/after arguments as defined by the GraphQL Cursor Connections Specification. You can find a less formal introduction in the GraphQL introduction.

For example, output the page of results containing up to five adventures, starting from the given cursor item in the complete results list:

query {
    adventurePaginated(first: 5, after: "ODg1MmMyMmEtZTAzMy00MTNjLThiMzMtZGQyMzY5ZTNjN2M1") {
        edges {
          cursor
          node {
            title
          }
        }
        pageInfo {
          endCursor
          hasNextPage
        }
    }
}

GraphQL Persisted Queries - enabling caching in the Dispatcher graphql-persisted-queries-enabling-caching-dispatcher

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.

Enable caching of persisted queries enable-caching-persisted-queries

To enable the caching of persisted queries, the following updates to the Dispatcher configuration files are required:

CORS configuration in the Dispatcher cors-configuration-in-dispatcher

Customers using CORS requests, might need to review and update their CORS configuration in the Dispatcher.

GraphQL for AEM - Summary of Extensions graphql-extensions

The basic operation of queries with GraphQL for AEM adhere to the standard GraphQL specification. For GraphQL queries with AEM, there are a few extensions:

CORS Filter cors-filter

To access the GraphQL endpoint, configure a CORS policy in the customer Git repository. This configuration is done by adding an appropriate OSGi CORS configuration file for one or more desired endpoints.

This configuration must specify a trusted website origin alloworigin or alloworiginregexp for which access must be granted.

For example, to grant access to the GraphQL endpoint and persisted queries endpoint for https://my.domain you can use:

{
  "supportscredentials":true,
  "supportedmethods":[
    "GET",
    "HEAD",
    "POST"
  ],
  "exposedheaders":[
    ""
  ],
  "alloworigin":[
    "https://my.domain"
  ],
  "maxage:Integer":1800,
  "alloworiginregexp":[
    ""
  ],
  "supportedheaders":[
    "Origin",
    "Accept",
    "X-Requested-With",
    "Content-Type",
    "Access-Control-Request-Method",
    "Access-Control-Request-Headers"
  ],
  "allowedpaths":[
    "/content/_cq_graphql/global/endpoint.json",
    "/graphql/execute.json/.*"
  ]
}

If you have configured a vanity path for the endpoint, you can also use it in allowedpaths.

Referrer Filter referrer-filter

In addition to CORS configuration, a Referrer filter must be configured to allow access from third-party hosts.

This filter is done by adding an appropriate OSGi Referrer Filter configuration file that:

For example, to grant access for requests with the Referrer my.domain you can:

{
    "allow.empty":false,
    "allow.hosts":[
      "my.domain"
    ],
    "allow.hosts.regexp":[
      ""
    ],
    "filter.methods":[
      "POST",
      "PUT",
      "DELETE",
      "COPY",
      "MOVE"
    ],
    "exclude.agents.regexp":[
      ""
    ]
}

Limitations limitations

To protect against potential problems there are default limitations imposed on your queries:

You also need to aware of:

Authentication authentication

See Authentication for Remote AEM GraphQL Queries on Content Fragments.

FAQs faqs

Questions that have arisen:

Tutorial - Getting Started with AEM Headless and GraphQL tutorial

Looking for a hands-on tutorial? Check out Getting Started with AEM Headless and GraphQL end-to-end tutorial illustrating how to build-out and expose content using AEM’s GraphQL APIs and consumed by an external app, in a headless CMS scenario.