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.

NOTE
AEM GraphQL API is a customized implementation, based on the standard GraphQL API specification.

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.

NOTE
See GraphQL.org and GraphQL.com.

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.

NOTE
The AEM GraphQL API implementation is based on the GraphQL Java libraries.

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.

JSON Preview

Actually Using the AEM GraphQL API

Initial Setup

Before starting with queries on your content you need to:

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

GraphiQL Interface

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

Experience Manager


Rapid Feature Releases with AEM Cloud: Telegraph Media Group’s RDE Strategy

Online | Session | Intermediate

Hear how Telegraph Media Group, the award-winning publisher of The Daily Telegraph, The Sunday Telegraph, The Telegraph Magazine,...

Wed, Mar 19, 3:30 PM PDT (10:30 PM UTC)

Register

How EY Enhanced Regulatory Knowledge Management with Adobe Solutions

Online | Session | General Audience

Delve into how EY leverages Adobe solutions to enhance regulatory knowledge management. EY leverages search analytics and personalization...

Wed, Mar 19, 4:00 PM PDT (11:00 PM UTC)

Register

Connect with Experience League at Summit!

Get front-row access to top sessions, hands-on activities, and networking—wherever you are!

Learn more