How to Access Your Content via AEM Delivery APIs

In this part of the AEM Headless Developer Journey, you can learn how to use GraphQL queries to access the content of your Content Fragments and feed it to your app (headless delivery).

The Story So Far

In the previous document of the AEM headless journey, How to Model Your Content you learned the basics of content modeling in AEM, so you should now understand how to model your content structure, then realize that structure using AEM Content Fragment Models and Content Fragments:

• Recognize the concepts and terminology related to content modeling.
• Understand why content modeling is needed for Headless content delivery.
• Understand how to realize this structure using AEM Content Fragment Models (and author content with Content Fragments.
• Understand how to model your content; principles with basic samples.

This article builds on those fundamentals so you understand how to access your existing headless content in AEM using the AEM GraphQL API.

• Audience: Beginner
• Objective: Learn how to access the content of your Content Fragments using AEM GraphQL queries:
  • Introduce GraphQL and the AEM GraphQL API.
  • Dive into the details of the AEM GraphQL API.
  • Look at some sample queries to see how things work in practice.

So You’d Like to Access Your Content?

So…you’ve got all this content, neatly structured (in Content Fragments), and just waiting to feed your new app. Question is - how to get it there?

What you need is a way to target specific content, select what you need and return it to your app for further processing.

With Adobe Experience Manager (AEM), you can selectively access your Content Fragments, using the AEM GraphQL API, to return only the content that you need. This means you can realize headless delivery of structured content for use in your applications.

GraphQL - An Introduction

GraphQL is an open-source specification that provides:

• a query language that enables you to select specific content from structured objects.
• a runtime to fulfill these queries with your structured content.

GraphQL is a strongly typed API. This means that all content must be clearly structured and organized by type, so that GraphQL understands what to access and how. The data fields are defined within GraphQL schemas, that define the structure of your content objects.

GraphQL endpoints then provide the paths that respond to the GraphQL queries.

All this means that your app can accurately, reliably and efficiently select the content that it needs - just what you need when used with AEM.

AEM GraphQL API

The AEM GraphQL API is a customized version based on the standard GraphQL API specification, specially configured to let you perform (complex) queries on your Content Fragments.

Content Fragments are used, as the content is structured according to Content Fragment Models. This fulfills a basic requirement of GraphQL.

• A Content Fragment Model is built up of one, or more, fields.
  • Each field is defined according to a Data Type.
• Content Fragment Models are used to generate the corresponding AEM GraphQL Schemas.

To actually access GraphQL for AEM (and the content) an endpoint is used to provide the access path.

The content returned, via the AEM GraphQL API, can then be used by your applications.

To help you directly input, and test queries, an implementation of the standard GraphiQL interface is also available for use with AEM GraphQL (this can be installed with AEM). It provides features such as syntax-highlighting, auto-complete, auto-suggest, together with a history and online documentation.

Content Fragments for use with the AEM GraphQL API

Content Fragments can be used as a basis for GraphQL for AEM schemas and queries as:

• They enable you to design, create, curate and publish page-independent content that can be delivered headlessly.
• They are based on a Content Fragment Model, which pre-defines the structure for the resulting fragment using a selection of data types.
• Additional layers of structure can be achieved with the Fragment Reference data type, available when defining a model.

Content Fragment Models

These Content Fragment Models:

• Are used to generate the Schemas, once Enabled.
• Provide the data types and fields required for GraphQL. They ensure that your application only requests what is possible, and receives what is expected.
• The data type Fragment References can be used in your model to reference another Content Fragment, and so introduce additional levels of structure.

Fragment References

The Fragment Reference:

• Is a specific data type available when defining a Content Fragment Model.

• References another fragment, dependent on a specific Content Fragment Model.

• Lets you create, and then retrieve, structured data.

  • When defined as a multifeed, multiple sub-fragments can be referenced (retrieved) by the prime fragment.

JSON Preview

To help with designing and developing your Content Fragment Models, you can preview JSON output in the Content Fragment Editor.

Actually Using the AEM GraphQL API

Initial Setup

Before starting with queries on your content you need to:

• Enable your endpoint

  • Use Tools > Assets > GraphQL
  • Enabling your GraphQL Endpoint

• Access GraphiQL (if necessary)

  • AEM GraphiQL interface

Sample Structure

To actually use the AEM GraphQL API in a query, we can use the two very basic Content Fragment Model structures:

• Company
  • Name - Text
  • CEO (Person) - Fragment Reference
  • Employees (Persons) - Fragment Reference(s)
• Person
  • Name - Text
  • First Name - Text

As you can see, the CEO and Employees fields, reference the Person fragments.

The fragment models is used:

• when creating the content in the Content Fragment Editor
• to generate the GraphQL schemas that you will query

Where to Test Your Queries

The queries can be entered in the GraphiQL interface, for example, at:

• http://localhost:4502/aem/graphiql.html

Getting Started with Queries

A straightforward query is to return the name of all entries in the Company schema. Here you request a list of all company names:

query {
  companyList {
    items {
      name
    }
  }
}

A slightly more complex query is to select all persons that do not have a name of “Jobs”. This will filter all persons for any that do not have the name Jobs. This is achieved with the EQUALS_NOT operator (there are many more):

query {
  personList(filter: {
    name: {
      _expressions: [
        {
          value: "Jobs"
          _operator: EQUALS_NOT
        }
      ]
    }
  }) {
    items {
      name
      firstName
    }
  }
}

You can also build up more complex queries. For example, query for all companies that have at least one employee with the name of “Smith”. This query illustrates filtering for any person of name “Smith”, returning information from across the nested fragments:

query {
  companyList(filter: {
    employees: {
      _match: {
        name: {
          _expressions: [
            {
              value: "Smith"
            }
          ]
        }
      }
    }
  }) {
    items {
      name
      ceo {
        name
        firstName
      }
      employees {
        name
        firstName
      }
    }
  }
}

For the full details of using the AEM GraphQL API, together with configuring the necessary elements, you can reference:

• Learning to use GraphQL with AEM
• The Sample Content Fragment Structure
• Learning to use GraphQL with AEM - Sample Content and Queries

What’s Next

Now that you have learned how to access and query your headless content using the AEM GraphQL API you can now learn how to use the REST API to access and update the content of your Content Fragments.

Additional Resources

• GraphQL.org
  • Schemas
  • Variables
  • GraphQL Java libraries
• GraphiQL
• Learning to use GraphQL with AEM
  • Enabling your GraphQL Endpoint
  • Installing the AEM GraphiQL interface
• The Sample Content Fragment Structure
• Learning to use GraphQL with AEM - Sample Content and Queries
  • Sample Query - A Single Specific City Fragment
  • Sample Query for Metadata - List the Metadata for Awards titled GB
  • Sample Query - All Cities with a Named Variation
• Enable Content Fragment Functionality in Configuration Browser
• Working with Content Fragments
  • Content Fragment Models
  • JSON output
• Understand Cross-Origin Resource Sharing (CORS)
• Getting Started with AEM Headless - A short video tutorial series giving an overview of using AEM’s headless features, including content modeling and GraphQL.