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)
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
-
Learning to use GraphQL with AEM - Sample Content and Queries
-
Enable Content Fragment Functionality in Configuration Browser
-
Getting Started with AEM Headless - A short video tutorial series giving an overview of using AEM’s headless features, including content modeling and GraphQL.
Experience Manager
Rapid Feature Releases with AEM Cloud: Telegraph Media Group’s RDE Strategy
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)
How EY Enhanced Regulatory Knowledge Management with Adobe Solutions
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)
Connect with Experience League at Summit!
Get front-row access to top sessions, hands-on activities, and networking—wherever you are!
Learn more