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).
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’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.
AEM GraphQL API is a customized implementation, based on the standard GraphQL API specification.
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.
See GraphQL.org and GraphQL.com.
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.
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.
The AEM GraphQL API implementation is based on the GraphQL Java libraries.
Content Fragments can be used as a basis for GraphQL for AEM schemas and queries as:
These Content Fragment Models:
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.
To help with designing and developing your Content Fragment Models, you can preview JSON output in the Content Fragment Editor.
Before starting with queries on your content you need to:
Enable your endpoint
Access GraphiQL (if necessary)
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 is used:
The queries can be entered in the GraphiQL interface, for example, at:
http://localhost:4502/aem/graphiql.html
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:
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.