XM Cloud: How to work with GraphQL in your local environment

by Freddy Rueda Barros , @freddy rueda on Slack.

One of the things that changed when we started working with XM Cloud is the fact that we are not able to use something similar to GetItem or GetChildren methods directly, as we are used to doing in XP.

When we need to retrieve an item, or items, from the content tree we need to use GraphQL. In the beginning, it would be challenging and confusing, but in this blog, I will give you the basics to start with it, after that, it will be easy to continue 🙂

GraphQL, our new best friend.

GraphQL is a query language that helps us to retrieve data from APIs, but the data we really need or want. Sitecore gives us a GraghQL endpoint that lets us get the information on our published content.

The official Sitecore documentation about XM Cloud and GraphQL is here. Basically mentions that there are 2 GraphQL APIs, Delivery and Preview. The first one (Delivery) is to retrieve published content, and the second one (Preview) is to retrieve information on the items in Content Management, regardless of what is published to Edge.

The tool given to run queries is called GraphQL Playground, or simply GraphQL IDE, and its URL is https://edge.sitecorecloud.io/api/graphql/ide.

Sitecore gives a list of query examples on this page. You can start with this to play with some queries and familiarize yourself with GraphQL and how retrieves information about our Sitecore items.

The Situation

When we start an XM Cloud project, the requirements come, and with those, the real challenges. For example, we already have our templates and create on our local environment the items of those templates, populate our content tree, create our renderings, and so on, and we need to create a Navigation component based on a content structure, for example:

The Navigation item has its child and grandchild items that represent the menu of our sample site. But remember this is in our development environment, it hasn’t been deployed nor published yet, but the playground IDE is pointing to Cloud Edge, how to test a query in our local environment?

The Solution

When we work with a local instance of XM Cloud, with our containers running well, the Playground IDE comes by default, but we need to set correctly the URL and the ApiKey parameters to run against the local items and look what is the result of a query.

In the image above, the 3 important things we have to set up are:

1. The url to launch the Playground IDE locally:

https://xmcloudcm.localhost/sitecore/api/authoring/graphql/ide/

2. The local endpoint to reach GraphQL API:

https://xmcloudcm.localhost/sitecore/api/graph/edge

3. The ApiKey:

The ApiKey is the ID value of the Sitecore item of our local XM located in /sitecore/system/Settings/Services/API Keys/xmcloudpreview

And it has to match the value of the variable of our .env file in the NextJs solution:

The Result

After all the configurations mentioned before, we are ready to run any query against our local data. Remember our Navigation item and its children’s items? the result of the query to retrieve those items is the following:

Sitecore GraphQL Documentation

As we are starting with GraphQL, The Playground IDE comes with a Docs section very useful for knowing what to ask to the API, it is the DOCS button on the right side of the screen.

In our example, we are retrieving the URL and the path of the items of the specific Navigation item. Look how the documentation helps us to retrieve what we want:

And that’s it! Now we know how to work locally with GraphQL and see what will be the result of our queries before coding them in our solution.

I hope that this will help you to start playing with the powerful Sitecore GraphQL endpoint.

Happy GraphQL coding 🙂 ! #XMCloud #GraphQL #Sitecore