Learn how to use Content Fragments in Adobe Experience Manager (AEM) as a Cloud Service with the AEM GraphQL API for headless content delivery.
AEM as a Cloud Service GraphQL API used with Content Fragments is heavily based on the standard, open source GraphQL API.
Using the GraphQL API in AEM enables the efficient delivery of Content Fragments to JavaScript clients in headless CMS implementations:
GraphQL is currently used in two (separate) scenarios in Adobe Experience Manager (AEM) as a Cloud Service:
GraphQL is:
“…a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.”.
See GraphQL.org
“…an open spec for a flexible API layer. Put GraphQL over your existing backends to build products faster than ever before…”.
See Explore GraphQL.
“…a data query language and specification developed internally by Facebook in 2012 before being publicly open sourced in 2015. It provides an alternative to REST-based architectures with the purpose of increasing developer productivity and minimizing amounts of data transferred. GraphQL is used in production by hundreds of organizations of all sizes…”
See GraphQL Foundation.
For further information about the GraphQL API, see the following sections (amongst many other resources):
At graphql.org:
At graphql.com:
The GraphQL for AEM implementation is based on the standard GraphQL Java Library. See:
GraphQL uses the following:
The path in AEM that responds to GraphQL queries, and provides access to the GraphQL schemas.
See Enabling your GraphQL Endpoint for further details.
See the (GraphQL.org) Introduction to GraphQL for comprehensive details, including the Best Practices.
With GraphQL you can perform queries to return either:
A single entry
AEM provides capabilities to convert queries (both types) to Persisted Queries, that can be cached by Dispatcher and the CDN.
The Persisted Queries are the recommended method to be used on publish instances as:
Usually there is no dispatcher/CDN on author, so there is no gain in using persisted queries there; apart from testing them.
GraphQL queries using POST requests are not recommended as they are not cached, so on a default instance the Dispatcher is configured to block such queries.
While GraphQL also supports GET requests, these can hit limits (for example the length of the URL) that can be avoided using Persisted Queries.
To allow direct, and/or POST, queries in the Dispatcher you can ask your System Administrator to:
ENABLE_GRAPHQL_ENDPOINT
true
The ability to perform direct queries may be deprecated at some point in the future.
You can test and debug GraphQL queries using the GraphiQL IDE.
The use cases can depend on the type of AEM as a Cloud Service environment:
Publish environment; used to:
Author environment; used to:
The permissions are those required for accessing Assets.
GraphQL queries are executed with the permission of the AEM user of the underlying request. If the user does not have read access to some fragments (stored as Assets), they will not become part of the result set.
Also, the user needs to have access to a GraphQL endpoint to be able to execute GraphQL queries.
GraphQL is a strongly typed API, which means that data must be clearly structured and organized by type.
The GraphQL specification provides a series of guidelines on how to create a robust API for interrogating data on a certain instance. To do this, a client needs to fetch the Schema, which contains all the types necessary for a query.
For Content Fragments, the GraphQL schemas (structure and types) are based on Enabled Content Fragment Models and their data types.
All the GraphQL schemas (derived from Content Fragment Models that have been Enabled) are readable through the GraphQL endpoint.
This means that you need to ensure that no sensitive data is available, as it could be leaked this way; for example, this includes information that could be present as field names in the model definition.
For example, if a user created a Content Fragment Model called Article
, then AEM generates a GraphQL type ArticleModel
. The fields within this type correspond to the fields and data types defined in the model. In addition, it creates some entrypoints for the queries that operate on this type, such as articleByPath
or articleList
.
A Content Fragment Model:
The corresponding GraphQL schema (output from GraphiQL automatic documentation):
This shows that the generated type ArticleModel
contains several fields.
Three of them have been controlled by the user: author
, main
and referencearticle
.
The other fields were added automatically by AEM, and represent helpful methods to provide information about a certain Content Fragment; in this example, (the helper fields) _path
, _metadata
, _variations
.
After a user creates a Content Fragment based on the Article model, it can then be interrogated through GraphQL. For examples, see the Sample Queries (based on a sample Content Fragment structure for use with GraphQL).
In GraphQL for AEM, the schema is flexible. This means that it is auto-generated each and every time a Content Fragment Model is created, updated or deleted. The data schema caches are also refreshed when you update a Content Fragment Model.
The data schema caches are also refreshed when you update a Content Fragment Model.
The Sites GraphQL service listens (in the background) for any modifications made to a Content Fragment Model. When updates are detected, only that part of the schema is regenerated. This optimization saves time and provides stability.
So for example, if you:
Install a package containing Content-Fragment-Model-1
and Content-Fragment-Model-2
:
Model-1
and Model-2
will be generated.Then modify Content-Fragment-Model-2
:
Only the Model-2
GraphQL type will get updated.
Whereas Model-1
will remain the same.
This is important to note in case you want to do bulk updates on Content Fragment Models through the REST api, or otherwise.
The schema is served through the same endpoint as the GraphQL queries, with the client handling the fact that the schema is called with the extension GQLschema
. For example, performing a simple GET
request on /content/cq:graphql/global/endpoint.GQLschema
will result in the output of the schema with the Content-type: text/x-graphql-schema;charset=iso-8859-1
.
When Content Fragments are nested it can happen that a parent Content Fragment Model is published, but a referenced model is not.
The AEM UI prevents this happening, but if publishing is made programmatically, or with content packages, it can occur.
When this happens, AEM generates an incomplete Schema for the parent Content Fragment Model. This means that the Fragment Reference, which is dependent on the unpublished model, is removed from the schema.
Within the schema there are individual fields, of two basic categories:
Fields that you generate.
A selection of Data Types are used to create fields based on how you configure your Content Fragment Model. The field names are taken from the Property Name field of the Data Type tab.
multifield
from the dropdown.GraphQL for AEM also generates a number of helper fields.
GraphQL for AEM supports a list of types. All the supported Content Fragment Model Data Types and the corresponding GraphQL types are represented:
Content Fragment Model - Data Type | GraphQL Type | Description |
---|---|---|
Single line Text | String , [String] |
Used for simple strings such as author names, location names, etc. |
Multi line Text | String , [String] |
Used for outputting text such as the body of an article |
Number | Float , [Float] |
Used to display floating point number and regular numbers |
Boolean | Boolean |
Used to display checkboxes → simple true/false statements |
Date And Time | Calendar |
Used to display date and time in an ISO 8601 format. Depending on the type selected, there are three flavors available for use in AEM GraphQL: onlyDate , onlyTime , dateTime |
Enumeration | String |
Used to display an option from a list of options defined at model creation |
Tags | [String] |
Used to display a list of Strings representing Tags used in AEM |
Content Reference | String , [String] |
Used to display the path towards another asset in AEM |
Fragment Reference | A model type Single field: Model - Model type, referenced directly Multifield, with one referenced type: [Model] - Array of type Model , referenced directly from array Multifield, with multiple referenced types: [AllFragmentModels] - Array of all model types, referenced from array with union type |
Used to reference one, or more, Content Fragments of certain Model Types, defined when the model was created |
In addition to the data types for user generated fields, GraphQL for AEM also generates a number of helper fields in order to help identify a Content Fragment, or to provide additional information about a Content Fragment.
These helper fields are marked with a preceding _
to distinguish between what has been defined by the user and what has been auto-generated.
The path field is used as an identifier in AEM GraphQL. It represents the path of the Content Fragment asset inside the AEM repository. We have chosen this as the identifier of a Content Fragment, because it:
The following code will display the paths of all Content Fragments that were created based on the Content Fragment Model Author
, as provided by the WKND tutorial.
{
authorList {
items {
_path
}
}
}
To retrieve a single Content Fragment of a specific type, you also need to determine its path first. For example:
{
authorByPath(_path: "/content/dam/wknd-shared/en/contributors/sofia-sj-berg") {
item {
_path
firstName
lastName
}
}
}
See Sample Query - A Single Specific City Fragment.
Through GraphQL, AEM also exposes the metadata of a Content Fragment. Metadata is the information that describes a Content Fragment, such as the title of a Content Fragment, the thumbnail path, the description of a Content Fragment, the date it was created, amongst others.
Because Metadata is generated through the Schema Editor and as such does not have a specific structure, the TypedMetaData
GraphQL type was implemented to expose the metadata of a Content Fragment. TypedMetaData
exposes the information grouped by the following scalar types:
Field |
---|
stringMetadata:[StringMetadata]! |
stringArrayMetadata:[StringArrayMetadata]! |
intMetadata:[IntMetadata]! |
intArrayMetadata:[IntArrayMetadata]! |
floatMetadata:[FloatMetadata]! |
floatArrayMetadata:[FloatArrayMetadata]! |
booleanMetadata:[BooleanMetadata]! |
booleanArrayMetadata:[booleanArrayMetadata]! |
calendarMetadata:[CalendarMetadata]! |
calendarArrayMetadata:[CalendarArrayMetadata]! |
Each scalar type represents either a single name-value pair or an array of name-value pairs, where the value of that pair is of the type it was grouped in.
For example, if you want to retrieve the title of a Content Fragment, we know that this property is a String property, so we would query for all the String Metadata:
To query for metadata:
{
authorByPath(_path: "/content/dam/wknd-shared/en/contributors/sofia-sj-berg") {
item {
_metadata {
stringMetadata {
name
value
}
}
}
}
}
You can view all the metadata GraphQL types if you view the Generated GraphQL schema. All model types have the same TypedMetaData
.
Difference between normal and array metadata
Keep in mind that StringMetadata
and StringArrayMetadata
both refer to what is stored in the repository, not how you retrieve them.
So for example, by calling the stringMetadata
field, you would receive an array of all the metadata that was stored in the repository as a String
, and if you call stringArrayMetadata
you would receive an array of all the metadata that was stored in the repository as String[]
.
See Sample Query for Metadata - List the Metadata for Awards titled GB.
The _variations
field has been implemented to simplify querying the variations that a Content Fragment has. For example:
{
authorByPath(_path: "/content/dam/wknd-shared/en/contributors/ian-provo") {
item {
_variations
}
}
}
Note that the _variations
field does not contain a master
variation, as technically the original data (referenced as Master in the UI) is not considered an explicit variation.
See Sample Query - All Cities with a Named Variation.
If the given variation does not exist for a Content Fragment, then the original data (also known as the master variation) will be returned as a (fallback) default.
GraphQL permits variables to be placed in the query. For more information you can see the GraphQL documentation for Variables.
For example, to get all Content Fragments of type Author
in a specific variation (if available), you can specify the argument variation
in GraphiQL.
Query:
query($variation: String!) {
authorList(variation: $variation) {
items {
_variation
lastName
firstName
}
}
}
Query Variables:
{
"variation": "another"
}
This query will return the full list of authors. Authors without the another
variation will fall back to the original data (_variation
will report master
in this case).
If you want to restrict the list to authors that provide the specified variation (and skip authors that would fall back to the original data), you’ll need to apply a filter:
query($variation: String!) {
authorList(variation: $variation, filter: {
_variation: {
_expressions: {
value: $variation
}
}
}) {
items {
_variation
lastName
firstName
}
}
}
In GraphQL there is a possibility to change the query based on variables, called GraphQL Directives.
For example there you can include the adventurePrice
field in a query for all the AdventureModels
, based on a variable includePrice
.
Query:
query GetAdventureByType($includePrice: Boolean!) {
adventureList {
items {
title
price @include(if: $includePrice)
}
}
}
Query Variables:
{
"includePrice": true
}
You can also use filtering in your GraphQL queries to return specific data.
Filtering uses a syntax based on logical operators and expressions.
The most atomic part is a single expression that can be applied to the content of a certain field. It compares the content of the field with a given constant value.
For example, the expression
{
value: "some text"
_op: EQUALS
}
would compare the content of the field with the value some text
and succeeds if the content equals the value. Otherwise, the expression will fail.
The following operators can be used to compare fields to a certain value:
Operator | Type(s) | The expression succeeds if … |
---|---|---|
EQUALS |
String , ID , Boolean |
… the value is exactly the same as the content of the field |
EQUALS_NOT |
String , ID |
… the value is not the same as the content of the field |
CONTAINS |
String |
… the content of the field contains the value ({ value: "mas", _op: CONTAINS } will match Christmas , Xmas , master , …) |
CONTAINS_NOT |
String |
… the content of the field does not contain the value |
STARTS_WITH |
ID |
… the ID starts with a certain value ({ value: "/content/dam/", _op: STARTS_WITH will match /content/dam/path/to/fragment , but not /namespace/content/dam/something |
EQUAL |
Int , Float |
… the value is exactly the same as the content of the field |
UNEQUAL |
Int , Float |
… the value is not the same as the content of the field |
GREATER |
Int , Float |
… the content of the field is greater than the value |
GREATER_EQUAL |
Int , Float |
… the content of the field is greater than or equal to the value |
LOWER |
Int , Float |
… the content of the field is lower than the value |
LOWER_EQUAL |
Int , Float |
… the content of the field is lower than or equal to the value |
AT |
Calendar , Date , Time |
… the content of the field is exactly the same as the value (including timezone setting) |
NOT_AT |
Calendar , Date , Time |
… the content of the field is not the same as the value |
BEFORE |
Calendar , Date , Time |
… the point in time denoted by the value is before the point in time denoted by the content of the field |
AT_OR_BEFORE |
Calendar , Date , Time |
… the point in time denoted by the value is before or at the same point in time denoted by the content of the field |
AFTER |
Calendar , Date , Time |
… the point in time denoted by the value is after the point in time denoted by the content of the field |
AT_OR_AFTER |
Calendar , Date , Time |
… the point in time denoted by the value is after or at the same point in time denoted by the content of the field |
Some types also allow to specify additional options that modify how an expression is evaluated:
Option | Type(s) | Description |
---|---|---|
_ignoreCase |
String |
Ignores the case of a string, e.g. a value of time will match TIME , time , tImE , … |
_sensitiveness |
Float |
Allows a certain margin for float values to be considered the same (to work around technical limitations due to the internal representation of float values; should be avoided, as this option might have a negative impact on performance |
Expressions can be combined to a set with the help of a logical operator (_logOp
):
OR
- the set of expressions will succeed if at least one expression succeedsAND
- the set of expressions will succeed if all expressions succeed (default)Each field can be filtered by its own set of expressions. The expression sets of all fields mentioned in the filter argument will eventually be combined by its own logical operator.
A filter definition (passed as the filter
argument to a query) contains:
lastName
field in the filter for the lastName
field in the Data (field) Type)_expressions
array, providing the expression set, and the _logOp
field that defines the logical operator the expressions should be combined withvalue
field) and the operator (_operator
field) the content of a field should be compared toNote that you can omit _logOp
if you want to combine items with AND
and _operator
if you want to check for equality, as these are the default values.
The following example demonstrates a full query that filters all persons that have a lastName
of Provo
or containing sjö
, independent of the case:
{
authorList(filter: {
lastname: {
_logOp: OR
_expressions: [
{
value: "sjö",
_operator: CONTAINS,
_ignoreCase: true
},
{
value: "Provo"
}
]
}
}) {
items {
lastName
firstName
}
}
}
While you can also filter on nested fields, it is not recommended, as it might lead to performance issues.
For further examples, see:
details of the GraphQL for AEM extensions
Sample Queries using this Sample Content and Structure
For best performance consider Updating your Content Fragments for Paging and Sorting in GraphQL Filtering.
This feature allows you to sort the query results according to a specified field.
The sorting criteria:
For example:
query {
authorList(sort: "lastName, firstName") {
items {
firstName
lastName
}
}
}
And also:
{
authorList(sort: "lastName DESC, firstName DESC") {
items {
lastName
firstName
}
}
}
You can also sort on a field within a nested fragment, using the format of nestedFragmentname.fieldname
.
This might have a negative impact on performance.
For example:
query {
articleList(sort: "authorFragment.lastName") {
items {
title
authorFragment {
firstName
lastName
birthDay
}
slug
}
}
}
For best performance consider Updating your Content Fragments for Paging and Sorting in GraphQL Filtering.
This feature allows you to perform paging on query types that returns a list. Two methods are provided:
offset
and limit
in a List
queryfirst
and after
in a Paginated
queryIn a ...List
query you can use offset
and limit
to return a specific subset of results:
offset
: Specifies the first data set to returnlimit
: Specifies the maximum number of data sets to be returnedFor example, to output the page of results containing up to five articles, starting from the fifth article from the complete results list:
query {
articleList(offset: 5, limit: 5) {
items {
authorFragment {
lastName
firstName
}
}
}
}
Paging requires a stable sort order to work correctly across multiple queries requesting different pages of the same result set. By default it uses the repository path of each item of the result set to make sure the order is always the same. If a different sort order is used, and if that sorting cannot be done at JCR query level, then there will be a negative performance impact as the entire result set must be loaded into memory before the pages can be determined.
The higher the offset, the more time it will take to skip the items from the complete JCR query result set. An alternative solution for large result sets is to use the Paginated query with first
and after
method.
The ...Paginated
query type reuses most of the ...List
query type features (filtering, sorting), but instead of using offset
/limit
arguments, it uses the first
/after
arguments as defined by the GraphQL Cursor Connections Specification. You can find a less formal introduction in the GraphQL introduction.
first
: The n
first items to return.50
.100
.after
: The cursor that determines the beginning of the requested page; note that the item represented by the cursor is not included in the result set; the cursor of an item is determined by the cursor
field of the edges
structure.For example, output the page of results containing up to five adventures, starting from the given cursor item in the complete results list:
query {
adventurePaginated(first: 5, after: "ODg1MmMyMmEtZTAzMy00MTNjLThiMzMtZGQyMzY5ZTNjN2M1") {
edges {
cursor
node {
title
}
}
pageInfo {
endCursor
hasNextPage
}
}
}
By default, paging uses the UUID of the repository node representing the fragment for ordering to ensure the order of results is always the same. When sort
is used, the UUID is implicitly used to ensure a unique sort; even for two items with identical sort keys.
Due to internal technical constraints, performance will degrade if sorting and filtering is applied on nested fields. Therefore it is recommended to use filter/sort fields stored at root level. This is also the recommended way if you want to query large paginated result sets.
Web-optimized image delivery allows you to use a Graphql query to:
Request a URL to an AEM Asset image
Pass parameters with the query, so that a specific rendition of the image is automatically generated and returned
The rendition specified is not stored in AEM Assets. The rendition is generated and held in cache for a short period.
Return the URL as part of the JSON delivery
You can use AEM to:
This means that the commands get applied during query execution, in the same way as URL parameters on GET requests for those images.
This allows you to dynamically create image renditions for JSON delivery, which avoids having to manually create and store those renditions in the repository.
The solution in GraphQL means you can:
use _dynamicUrl
on the ImageRef
reference
add _assetTransform
to the list header where your filters are defined
AssetTransform
(_assetTransform
) is used to make the URL transformation requests.
The structure and syntax is:
format
: an enumeration with all supported formats by its extension: GIF, PNG, PNG8, JPG, PJPG, BJPG, WEBP, WEBPLL or WEBPLYseoName
: a string that will be used as file name instead of the node namecrop
: a frame sub structure, if width or height is omitted then the height or width is used as the same value
xOrigin
: the x origin of the frame and is mandatoryyOrigin
: the y origin of the frame and is mandatorywidth
: the width of the frameheight
: the height of the framesize
: a dimension sub structure, if width or height is omitted then the height or width is used as the same value
width
: the width of the dimensionheight
: the height of the dimensionrotation
: an enumeration of all supported rotations: R90, R180, R270flip
: an enumeration of HORIZONTAL, VERTICAL, HORIZONTAL_AND_VERTICALquality
: an integer between 1 and 100 notating the percentage of the image qualitywidth
: an integer that defines the width of the output image but will be ignored by the Image GeneratorpreferWebp
: a boolean that indicates if webp is preferred (default value is false)The URL transform is available for all query types: by path, list or paginated.
The following is a sample query with a full set of parameters:
{
articleList(
_assetTransform: {
format:GIF
seoName:"test"
crop:{
xOrigin:10
yOrigin:20
width:50
height:45
}
size:{
height:100
width:200
}
rotation:R90
flip:HORIZONTAL_AND_VERTICAL
quality:55
width:123
preferWebp:true
}
) {
items {
_path
featuredImage {
... on ImageRef {
_dynamicUrl
}
}
}
}
}
The following example shows the use of a single query variable:
query ($seoName: String!) {
articleList(
_assetTransform: {
format:GIF
seoName:$seoName
crop:{
xOrigin:10
yOrigin:20
width:50
height:45
}
size:{
height:100
width:200
}
rotation:R90
flip:HORIZONTAL_AND_VERTICAL
quality:55
width:123
preferWebp:true
}
) {
items {
_path
featuredImage {
... on ImageRef {
_dynamicUrl
}
}
}
}
}
The following example shows the use of multiple query variables:
query ($seoName: String!, $format: AssetTransformFormat!) {
articleList(
_assetTransform: {
format:$format
seoName:$seoName
crop:{
xOrigin:10
yOrigin:20
width:50
height:45
}
size:{
height:100
width:200
}
rotation:R90
flip:HORIZONTAL_AND_VERTICAL
quality:55
width:123
preferWebp:true
}
) {
items {
_path
featuredImage {
... on ImageRef {
_dynamicUrl
}
}
}
}
}
If you save your query as a persisted query (for example, with the name dynamic-url-x
) you can then execute the persisted query directly.
For example, to directly execute the previous samples (saved as persisted queries), use the following URLs:
Single Parameter; Persisted Query named dynamic-url-x
http://localhost:4502/graphql/execute.json/wknd-shared/dynamic-url-x;seoName=xxx
The response will look like:
Multiple Parameters; Persisted Query named dynamic
http://localhost:4502/graphql/execute.json/wknd-shared/dynamic;seoName=billiboy;format=GIF;
The trailing ;
is mandatory to cleanly terminate the list of parameters.
The following limitations exist:
Modifiers applied to all images part of the query (global parameters)
Caching headers
The basic operation of queries with GraphQL for AEM adhere to the standard GraphQL specification. For GraphQL queries with AEM there are a few extensions:
If you require a single result:
If you expect a list of results:
List
to the model name; for example, cityList
You can then:
ASC
: ascendingDESC
: descendingReturn a page of results using either:
If you want to use a logical OR:
_logOp: OR
Logical AND also exists, but is (often) implicit
You can query on field names that correspond to the fields within the Content Fragment Model
In addition to the fields from your model, there are some system-generated fields (preceded by underscore):
For content:
_locale
: to reveal the language; based on Language Manager
_metadata
: to reveal metadata for your fragment
_model
: allow querying for a Content Fragment Model (path and title)
_path
: the path to your Content Fragment within the repository
_reference
: to reveal references; including inline references in the Rich Text Editor
_variation
: to reveal specific Variations within your Content Fragment
If the given variation does not exist for a Content Fragment, then the master variation will be returned as a (fallback) default.
For image delivery:
_dynamicUrl
: on the ImageRef
reference
_assetTransform
: on the list header where your filters are defined
See:
And operations:
_operator
: apply specific operators; EQUALS
, EQUALS_NOT
, GREATER_EQUAL
, LOWER
, CONTAINS
, STARTS_WITH
_apply
: to apply specific conditions; for example, AT_LEAST_ONCE
_ignoreCase
: to ignore the case when querying
GraphQL union types are supported:
Fallback when querying nested fragments:
To access the GraphQL endpoint from an external website you need to configure the:
See Authentication for Remote AEM GraphQL Queries on Content Fragments.
Questions that have arisen:
Q: “How is the GraphQL API for AEM different from Query Builder API?”
Looking for a hands-on tutorial? Check out Getting Started with AEM Headless and GraphQL end-to-end tutorial illustrating how to build-out and expose content using AEM’s GraphQL APIs and consumed by an external app, in a headless CMS scenario.