Getting Started with AEM Headless - GraphQL getting-started-with-aem-headless

Transcript

Hello, in this video, we’re going to look at the GraphQL API implemented in Adobe Experience Manager or AEM. The GraphQL API in AEM, is primarily designed to deliver content fragment data to downstream applications. So what is GraphQL? GraphQL is a query language for API’s and a runtime for executing these queries and returning results. Now that result set is typically in JSON format. Since that data format is platform diagnostic. GraphQL has become very popular for headless use cases, since client applications can create queries to return exactly the data that they want. So in this diagram, we have a server that contains all of the content. Server has implemented a suite of GraphQL API’s, designed to expose this content. Client applications, like mobile, desktop or IoT devices, can create GraphQL queries for the content they need to power their apps. Based on these queries, the GraphQL API will return the results.

Let’s look at some of the key benefits of a GraphQL API. As mentioned before, one of the reasons for a GraphQL’s popularity is that clients can create a query to get exactly the properties that they want. This in turn provides stability to downstream applications because they control the data being returned. Another key feature of GraphQL is the ability to fetch multiple resources with a single request. This could be a list of two unrelated pieces of content, like a list of persons and a list of countries joined in a single query. Or it could be a set of properties from a nested reference, say the city and zip code of the address of a person. Consolidating queries minimizes the number of HTTP requests an app needs to make, thereby increasing the speed and performance of the application. GraphQL API is strongly typed and ensures that applications can only ask for data based on the data model. This allows for clear and helpful error messages, predictable results and features like code completion when generating queries. GraphQL is designed to evolve with your data so that adds additional fields or properties are added, these are in turn exposed via the API.

AEM has implemented a set of GraphQL API’s to expose data about content fragments. Content fragments are a way to structure data in AEM and is typically object oriented. A content fragment can be represented by something like an article or person. Individual fields within a content fragment, capture properties like a name, height, or width. Now before a fragment can be created, a content fragment model is defined. Content fragment models are defined using a drag and drop friendly UI in AEM, and content fragment models define the data schema of properties for fragment. Content fragment models also serve as the authoring template. So this includes whether a text field, rich text field, number field are presented to the user when he or she is creating a content fragment. Now based on a model, content fragments are authored in AEM. Typically many fragments are created based off of a single model. Variations of the same content fragment can also be created for additional flexibility.

All content fragments created in an AEM, are exposed via the GraphQL APIs. Applications can query for a list of content fragments based on the model, or can request data about an individual fragment based on its location in AEM.

All of the properties available to be used in a GraphQL query, are based off of the fragments model. So whenever properties in a content fragment models change, the GraphQL API is automatically updated.

Content fragment models can have additional fields to reference other objects. This allows users to create complex data schemas with relationships between models and built-in content types. So for example, we have an address field in our person model, that references a different content fragment created based off of an address model. This is known as a fragment reference.

It is also possible to create references to other content types in AEM. For example, our person might have a picture, and this would be a reference to an image in AEM Assets. This is known as a content reference. When defining a content primary model, it’s possible to restrict the types of references possible. GraphQL allows developers to request properties of the primary model as well as any properties of the reference object. In the first query, address is a reference model, and we can request properties for the street, city and zip code, based on the address model. You can also see that picture is a reference to a built in content type image. Since this is a built-in object, developer would use the onImageRef syntax to request information about the pictures path, MIME type and height.

Second query serves as an example of GraphQL’s flexibility. Notice that the second query requests different attributes for the person list and does not request any information about the address. This again is one of the key benefits of GraphQL, in that, clients have full control over what data gets returned. Since GraphQL is strongly typed, these queries can be validated in advanced against the content fragment models data schema. So let’s quickly look at this in action. I’ll log in to my AEM environment. And I can navigate to view a list of content fragment models that have already been created.

If I open up the adventure content fragment model, you can see fields for title, description, adventure type and so on.

Each of these fields can be defined with different data types, available within the content fragment models editor. This includes types like single line of text, multi line, text, and many others.

Clicking one of the fields, I can view the properties that define that field. This includes how the field is rendered, the label and the property name. Additional validation is also available.

If I click on another field like contributor, you’ll notice that this is a fragment reference field. Here it is referencing another content fragment model named Contributor. Next, let’s look at a content fragment. Content fragments are managed as part of AEM Assets. Assets are stored in a folder-based hierarchy. So if I navigate into adventures, I can see a list of folders for different sample adventures. Clicking into one of the folders, I can see images as well as a content fragment.

This fragment is based off of the adventure content fragment model. And when I open it up, you can see the same fields as defined in the model but now we have some content. So this includes fields like the title and the description. I can also use the primary image field to reference an image located in AEM Assets.

Recall the fragment reference field from earlier. Fragment references allow us to easily choose another fragment. In this case, I’ll choose a Contributor. Once selected, I can open up the reference fragment for editing.

Let’s quickly look at how the data from these content fragments can be delivered via the GraphQL API’s. Built into AEM, is a tool called GraphQL. This tool allows us to quickly create and test new queries. GraphQL also has built in validation and code completion capabilities. To make it even easier to create these queries.

To get a list of all adventures in AEM, I can use the adventure list query. And then I can define several properties that I want returned for each item.

Notice that the available properties, are the same ones defined in the model.

Executing the query, I can see the results.

I’ll update the query to include the reference to the contributor. Since this is a fragment reference, I can then define the properties I want for that object.

Notice that the values for full name, path, and occupation, are returned from the referenced contributor model. GraphQL also has built in documentation. Since the GraphQL API is derived based on the models created in the current AEM environment, this is quite useful. Here I can see that it’s possible to filter our adventure list based on an adventure model filter.

Let’s go ahead and filter based on the adventure activity.

I’ll update the query to find only the result set for surfing. After executing the query, I can see there are now only two results.

The queries shown in this video, are just a sample to give you an idea of some of the powerful things you can do with GraphQL. Client applications can then implement these GraphQL queries to fetch data from AEM and power their app. Here I’ve got a react based application that displays a list of adventures from AEM. The react application performs a GraphQL query, to retrieve the data about the available adventures from AEM. If I click into one of the adventures, I can see more details about the adventure including the activity, type and itinerary. The adventure details are retrieved by executing another GraphQL query.

Using my browser’s developer tools, I can inspect the query to see if the raw query and AEM response.

Note that the response is in JSON format, exposing the data as JSON, gives the react application full control over how to present and layout the content.

So that concludes this video on using the GraphQL API in Adobe Experience Manager to expose content fragment data. Thanks for watching. -