XM Cloud - 10 Steps Of GraphQL Mutations Using Authoring APIs and Troubleshooting

 

Well, well, well

Believe me it's been tough getting my understanding around all the dots which we need to connect to make the GraphQL IDE to work, and top of it execute a successful query via it.

I am writing this blog to show what all troubleshooting i did, Couple of mistakes which i found, some new things that i had to learn along the way to make it work, Different types of APIs, and their meanings, like Preview API, Delivery API, Token API, Admin API, but all in summary, after this blog, i am sure no one should land into the issue like i did, that is the purpose.

NOTE: When you start reading out the documentation for the first time, there will be lot of confusions around what are all these APIs, and which one to use when? Different headers for different APIs, I will have a different blog explaining all of them but specially when you are working with or if you have questions around Authoring API, It is different because it does mutation operations against Sitecore CM, for CRUD operations, and other APIs like preview and delivery are to query against experience edge (GET only), This is the basic understanding you should have.

I am assuming that you already know what is GraphQL and how it is being used along with Sitecore as a new way of fetching data, i am not going to explain that because the scope is different but believe me i knew nothing about GraphQL and its syntax and where to write it, but its all part of learning that had, but i will quickly jump to the steps and issues that you will land in while trying to make GraphQL work.

Steps

We all start with the documentation which is available right? So on Walkthrough: Enabling and authorizing requests to the Authoring and Management API (sitecore.com) the steps are given and URL for IDE etc.

1) First confusion is which is the correct URL to hit in a browser, because i found two but thankfully both when hit in the browser, redirects to the same URL, Following are correct URLs you can use to open IDE

https://<<your xm cloud CM host>>/sitecore/api/authoring/graphql/ide
https://<<your xm cloud CM host>>/sitecore/api/authoring/graphql/playground 

Above both URLs are valid and will work 

2) Now, When you hit the URL, you will end up with "document not found page" or 404 page, Because by default the playground to enable authoring calls are disabled on XM Cloud, so you will have to enable it to be able to use the authoring API calls.

 3) To enable the playground On XM Cloud, On XM Cloud deploy app, From your environment, go to environment variables,and do following 

4) If it does not exist, make above entry and once done, you will need to deploy the environment again, like following

5) Now, once deployment is finished, you should hit the URL given on step-1 again, and it should load the GraphQL IDE

6) The actual problem starts now, When the IDE opens, the end point URL above is loaded and populated automatically, but it keeps giving "Server cannot be reached"

Note: I ignored it and just went ahead with other process of login and creating token and passed the token into the headers but i had no luck until i fix above

It took me couple of hours to try different things but it never was able to connect, After scratching my head for hours and pulling my hairs, i found out that, Following changes needs to be done before it starts working

• You have to give https:// instead of http:// which is wrong in default end point If you observe above screenshot, it is http:// by default
  
• You will have to remove /ide/../v1 and replace it with /v1/ (Note: without last slash also it was not working)
• Lastly, Remove the port 80 from the URL too
• Now, after doing all these changes, when you hit enter, the changes will take effect now this URL will work, Full modified URL is given below

https://<<Your xm cloud cm end point>>/sitecore/api/authoring/graphql/v1/ 

7)  Once you set the URL like above, you might still get following error when you try to run query 

{
  "error": "Unexpected token '<', \"<!DOCTYPE \"... is not valid JSON"
}

You just have to make sure that end point is correct like above, After that you just have to follow what is given on Sitecore documentation, of authorizing the IDE so it can make queries, login to cloud environment via command and generate the token which you can pass into header as following

8) Now, to authorize the IDE you will first have to login to cloud using command, and there are two ways to do it

• Login via simple "dotnet sitecore cloud login" command, you can run this from the powershell window from the same path as where your Sitecore.json is located, it will use ClientID and Secret of that file (Some how my user.json does not have Secret so i did option two as below)
• I created my own "Authentication Client" from XM Cloud portal, like following

It will give you ClientID and Secret, Make sure to keep it safe somewhere because secret will not be shown second time, you will need to generate a new authentication client if you loose it.

9) Now, Login with this details from powershell like following 

dotnet sitecore cloud login --client-credentials --client-id <your-client-id> --client-secret <your-client-secret> --allow-write true --xmcloudhost <your-xmcloud-host> --authority <authority-url> --audience <audience-url>

You can replace other parameter by taking reference from user.json file or from Sitecore documentation i have given above on start of this blog

Once login is successful it will just return to a prompt, now you should be good to use same ClientID and Secret to get token like following

10) Generate token use following CURL command and hit it from the postman

curl --location --request POST '<authority-url>/oauth/token' --header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'client_id=<your-client-id>' --data-urlencode 'client_secret=<your-client-secret>' --data-urlencode 'audience=<audience-url>' --data-urlencode 'grant_type=client_credentials'

you can use import option of postman, and use raw option and paste above command with proper values replaced before running it, and create the call into postman 

Now, You are good to use GraphQL IDE and pass this token in the authorization header as shown below, and now if you create any GraphQL mutation query to do any authoring query, Like for example, i just created simple Blog item of my blog template type under the Blogs parent, you can see it below that it successfully created item into Sitecore.

And you can also see in my Sitecore, That item is created.

Being honest, but i was very happy to achieve this, As i did not know GQL, did not know Authentication Client, Did not know lot of things before and because there were some issues in URLs and processes, i was in never ending loop, But happy that its resolved now

Off for the day now, will enjoy the rest of the evening with family :)