GraphQL Persisted Queries

Transcript

Hello and welcome to the Adobe Experience Manager Headless series. In this video, we will take a look at Persisted Queries in AEM to help you with your headless use cases. Before getting started, let’s take a quick look at our learning objectives for this video. As you know, GraphQL allows clients to define and control the data returned for a given query. AEM’s Persisted Queries, on the other hand, delegate the query definition and data response format to the server. In short, Persisted Queries allow AEM administrators to define and persist standard GraphQL queries server-side. Server-side definition of queries allows for more control over an API, reduces query request complexity and offers implementation encapsulation. Persisted queries were introduced in AEM to allow for a server-side API architecture. There are several benefits to this model. First, remember that client-side GraphQL queries are executed via an HTTP POST request, thereby making it difficult to cache. Persisted queries, on the other hand, allow clients to execute a server-side GraphQL query via an HTTP GET request instead. This allows requests to be cached for performance. Second, client-side requests are simpler since the complexity of the queries are encapsulated on the server. Third, security is also improved as query and data can be fully controlled by an AEM administrator. Adobe recommends only using Persisted Queries in production for their aforementioned reasons. By the end of this video, you will have a good understanding of how to enable, create, update and execute Persisted Queries. Let’s begin by reviewing the project settings required to enable Persisted Queries. We will navigate to Tools, then Configuration Browser. Then select the project that you wish to enable. We will use the We Can Share project throughout this tutorial. Now select Properties. As you can see, GraphQL Persisted Queries are enabled for this project. You will also need to ensure that the project endpoint is created using the Endpoint Manager as shown in previous tutorials. Now that we have Persisted Queries enabled, let’s review the basics for creating, updating and executing queries. Persisted Queries are managed in the GraphQL Query Editor. Available on AEM Author at Tools, General, and then GraphQL Query Editor. First, select the endpoint that we want to use for the query. Picking the correct endpoint is important because it determines the configuration that your query will be applied to, and thus which content fragments and content fragment models it can query. With the appropriate endpoint selected, let’s create a query that lists the adventure content fragments. The payload for this request is simply a standard GraphQL query. This query will return a list of adventures in the We Can Share project and return two fields, Path and Title. Now let’s execute the query. Notice that we get a valid response. To persist our query, we can use the Save As option and name it something descriptive, like Adventure List Example. You can see that it’s added to the list of Persisted Queries. Because we have selected the We Can Share endpoint, you will also see some other Persisted Queries provided by this project you can explore later. If we need to update the query, simple select the Persisted Query from the list, add any new lines or modifications, then use Save to commit our update to the Persisted Query. You have the ability to adjust the cache life of your Persisted Queries by setting the time to live value to a specific duration. For instance, let’s say you want to change the TTL value of your Persisted Query. We will select the Headers option to open the Cache Configuration dialog. Let’s add six and save our changes. Remember to publish your Persisted Query after making any modifications to its cache settings. Once you have selected your Persisted Query from the list, on the left panel, you can choose to Publish or Unpublish it. This will activate the query in your AAM publish service. The globe icon next to the Persisted Query indicates if it’s published. Additionally, you can use the Copy URL option to simulate the query by copying the URL, used to directly access the Persisted Query. This can be useful for testing purposes, such as by accessing it in a browser to see the results. This concludes the Persisted Queries video. Thank you for joining us!