How to Access Your Content via AEM Delivery APIs access-your-content

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 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:

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

So You Would Like to Access Your Content? so-youd-like-to-access-your-content

So…you have 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) as a Cloud Service, 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-introduction

GraphQL is an open-source specification that provides:

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 aem-graphql-api

The AEM GraphQL API is a customized version based on the standard GraphQL API specification, specially configured to allow you to 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.

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-use-with-aem-graphql-api

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

Content Fragment Models content-fragments-models

These Content Fragment Models:

Fragment References fragment-references

The Fragment Reference:

JSON Preview 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 actually-using-aem-graphiql

Initial Setup initial-setup

Before starting with queries on your content you need to:

Sample Structure sample-structure

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

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

The fragment models are used:

Where to Test Your Queries where-to-test-your-queries

The queries can be entered in the GraphiQL interface. You can access the query editor from either:

Getting Started with Queries 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:

What’s Next whats-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 additional-resources