Creating GraphQL Queries

Transcript

Hello and welcome to the Adobe Experience Manager, headless video series. In this video, we’ll take a look at creating GraphQL queries to help you with your headless use cases. Before we get started, let’s take a look at some of our learning objectives. We’ll start by taking a brief look at GraphQL. GraphQL is a data query language and runtime for building modern APIs. It’s a good alternative to traditional REST-based APIs that favors a single request architecture. Unlike traditional APIs, GraphQL delegates authority back to the clients allowing with the client to choose which data it requires. Now that we have a high level view of GraphQL, let’s look at why it was introduced into Adobe Experience Manager. First, it provides efficient delivery of content fragments for your headless clients. Second, since it favors a single request architecture, it allows us to avoid multiple queries to Adobe Experience Manager. And lastly, since it is data-driven, it allows you to evolve your content APIs over time. In this tutorial, we’ll cover a few concepts. We’ll look at the benefits of GraphQL, the GraphQL tooling available in AEM, and simple and advanced GraphQL query creation. The best way to get started with GraphQL and AEM is to start experiment with queries using our sample content fragment data. In this tutorial, we’ll use the GraphiQL IDE to start experimenting with queries. This package is not available with AEM as it’s intended only for development use, but it is available for download in the software distribution portal. Once we’re on the software distribution portal, we need to navigate to AEM as a Cloud Service.

Next, we need to search for the GraphiQL content package. Note that GraphiQL is spelled with an I.

Next hit enter. There may be multiple versions available for the GraphiQL IDE, select the most recent version. Then agree to the end user license agreement and click the download button. Now that we’ve downloaded GraphiQL, let’s navigate back to AEM and go to tools, deployment, then packages. Now that we’re at the package manager, let’s upload our package, then browse, and we’ll select the package we just downloaded. Lastly, click okay, then install.

Now that our package is installed, let’s access the GraphiQL IDE by adjusting the URL. Enter slash content slash graphiql.html. Before we get started, let’s take a quick tour of the GraphiQL IDE.

Along the top, we have our primary controls. The first is our play button which allows us to execute queries. Prettify allows us to pre-format our JSON to make things easier to read. Merge allows us to merge queries, copy allows us to copy queries, and history allows us to see our previous queries. The IDE consists of three primary panels. The panel on your left is where you issue your queries. The panel to the right is where we get our query response. And the panel on the bottom is where we can define query variables. More on this later. We also have a document explorer to provide you with some helpful pointers. We’ll start by issuing our first query. A common use case is to query for a list of a particular content fragment. Let’s construct a simple request that I’ll ask AEM for a list of all the contributor content fragments. Next, let’s press the play button to execute our query. Notice that the query response roughly models the query we just sent. This is by design in GraphQL.

Let’s take a minute and build on this idea of how closely the request and response match each other. Let’s add another field to our query so that we can see it in our response. Let’s position our cursor after the path with a comma, hit enter and then we’ll use the auto suggest feature. Simply enter control and the space bar. Notice the list of other fields we defined in our model. Simply use the arrow key to find the property you’re interested in, then hit enter. We can continue this process to find and add more fields. Let’s take a look at some other features to help you build your queries within GraphiQL. GraphQL has a robust type system. contributorList is an example of a query type within GraphQL. AEM creates these based on your content fragment models. Let’s take a closer look of how to find the query types available in your instance of AEM. First, we’ll navigate to the document explorer. Next, we’ll navigate to query type. As you can see, we have several query types available to us. We have some for article, some for adventure, and some for contributor. These are the three content fragment models we have available in our system. AEM creates two query types by convention per content fragment model, each with a suffix following the model’s name. AEM supports two suffixes for your query types. The first is bypath and the second is list which we’ve seen so far. We’ll explore bypath in a minute. There’s one more area within the GraphQL type system we need to explore and that’s object types. We’ll take a look at the contributorList and it’s return type. Notice that it is contributor model results. Let’s click through.

Notice here we have an item’s property. This is the same one we’re using within our query, and we can see that the object type is called contributor model. As you can see, we have a list of all the fields representing our contributor model. You can use this as a reference in addition to the auto suggest to help you build your queries. Let’s build on this example and add another field. This time, we’ll use something a bit more complex. We’ll take a look at adding the biography field. Since the biography field uses the multiline text data type, we have a few options in terms of getting back data for rendering. First, we have html, plain text, markdown, and JSON. All four are not required but they are available based on your rendering use cases. This is a key point to remember with GraphQL. You have the ability as the client making the request to tailor the response that your application needs. Now, let’s consider how we can add the profile picture to the query. If you recall the profile picture field use the content fragment data type. Adding this kind of data type requires that we make a union type selection in the GraphQL world. We do this by indirectly querying the image ref fragment, here’s the syntax. Within profile picture, we’ll define an object type fragment spread. This consists of an ellipsis, on, and then our type, in our case image ref. Within image ref, we can define the list of fields we want. In our case, we’ll just include path. Next, let’s execute our query. As you can see, GraphQL does have its learning curve. So, you may want to take a look at the GraphQL documentation. Let’s take a quick moment to add a few more content fragments for our contributor content model. This will allow us to experiment a bit more with our list query as we’re going to move on to filtering results. Once you have two or more contributors in your system, we execute your query. Notice that we have two results now, one for Ivan Provo, and one for Justin Bar. Since each contributor has a different occupation, let’s use that to filter. We’ll go ahead and quickly add the occupation field back to our query. We’ve been calling our contributorList query type without arguments. It does in fact support arguments. So, let’s take a look at the documentation and see what’s available. As you can see this query type supports a filter. In fact, all the filters are created by convention within AEM. Let’s inspect the contributor model filter. Now let’s add a filter to our query type.

Then, we’ll search across the occupation field. We’ll use a simple expression and filter against influencer, all lower case.

Now, let’s re-execute our query. We’re left with contributors whose occupation is influencer. Now that we have some experience querying and filtering lists of content, let’s take a quick look at how to query a single content fragment. In this example, we’ll use a new query type. Let’s start by reverting our filter query. You can either do this manually or navigate to the history button.

As mentioned previously, every content fragment model in AEM also supports a query type with the suffix bypath. This takes one argument which is the path to the content fragment.

Let’s begin by copying the path for one of our contributors. Then, let’s adjust the query type from contributorList to contributorByPath.

Next, we’ll specify a path as single argument and paste our content fragment path. Lastly, we need to rename items to item.

Then let’s execute our query.

Let’s shift gears and explore a couple of powerful GraphQL features that make our queries a bit more flexible and useful. First, let’s see how we can add parameters to our GraphQL queries to make queries more dynamic. As an example, we’ll design a query that finds a contributorByPath. Let’s start by defining our GraphQL type and name it findContributorByPath. You can name this anything you like. Next, we’ll specify a single required string parameter. We’ll call it a path. The exclamation point indicates that this is required parameter. Now, let’s nest the contributorByPath query type that we’ve seen previously and define a path as an argument. If you recall, the contributorByPath is generated by AEM and supports a path parameter. Refer to the documentation explorer to see the full list of supported parameters used by the bypath query types in AEM. Now that our query is designed to support a single parameter, we need to define our parameters as a simple JSON object. Let’s scroll to the bottom of the GraphiQL interface. For our example, we’ll define a single variable. We need to specify a path and a valid path in AEM. In our case, we’ll specify the Ian Provo example path.

Now, let’s run our query. As you can see in the response, we now have a GraphQL query that can be used to look up data dynamically.

Before concluding the tutorial, let’s take a look at one more powerful feature within GraphQL. GraphQL offers the ability to specify multiple queries within the single request, and therefore help reduce round trip times. Let’s take a look and issue query against contributors and adventures. First, we’ll select and remove the entire query. And second, we’ll paste a query that includes two separate queries.

As you can see, we have adventureList and contributorList. Let’s hit the play button and see what we get. As you can see, we have a list of our adventures and if we scroll down, a list of our contributors.

That concludes our tour of creating GraphQL queries within Adobe Experience Manager. Stay tuned for future videos in the headless series. - -