Serge van den Oever's weblog

XM Cloud Deploy API

Tue Jan 17 2023 • ☕️ 4 min read • you like my writing? Buy me a coffee

XM Cloud Deploy API

XM Cloud Deploy manages both the Cloud CMS modifications deployment to XM, and the frontend code deployment to the internal editing host. This can be done through the provided web UI (https://deploy.sitecorecloud.io/) and the Sitecore CLI. In the blog post XM Cloud build and deploy like a pro I described how you can use PowerShell to automate deployments against the Sitecore CLI. But XM Cloud Deploy also provides a REST API that can be used to automate deployments. This REST API is also used by the XM Cloud Deploy web UI, so if you look at the network tab of your browser when performing actions in the web UI and filter on Fetch/XHR you will see all the REST API calls that are executed:

REST API calls executed by XM Cloud Deploy

And if you switch to the Headers tab you will see that the requests are done using an Authorization header with a bearer token:

r2o3amc232

The API host is also visible, e.g. https://xmclouddeploy-api.sitecorecloud.io which shows us what it is, the Sitecore XM CLoud GitOps API!:

r2o5amc252

Swagger and OpenAPI

Any good REST API uses Swagger to self-document the REST API, and so does the XM Cloud Deploy API. Open up the URL https://xmclouddeploy-api.sitecorecloud.io/swagger and you will see:

XM Cloud Deploy Swagger

What you will also see is a link to the OpenAPI specification of the REST API:

Open API link

This is a description of all available API calls in a JSON format:

OpenAPI specification in JSON

But what is the OpenAPI specification? In their own words:

The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.

The cool thing is that this specification can be used to create a client SDK for the REST API in any language that you like, so you don’t have to interact with the API on an HTTP level. See https://openapi.tools/ for a whole bunch of tools regarding OpenAPI:

Overview of OpenAPI.Tools website

Testing API calls in the Swagger UI

Another cool feature of the Swagger UI is that you can test out API calls. Because the XM Cloud Deploy REST API needs authentication, you first need to authenticate in the Swagger UI. Do this through the Authorize button in the Swagger UI:

The Swagger authorize button

Then copy the value of the Authorization header from the requests in the network tabn to the Value field and press Authorize:

Authorize by pasting the value of the authorization header

This results in the correct authorization:

Authorized!

Close the window, and now you can test out the different API calls in the Swagger UI. As an example open the /api/sourcecontrol/v1/templates call by selecting the down arrow on the right side:

The sourcecontrol templates call in Swagger

You will see the parameters (provider in this case) and the expected response in case of a correct result (200 return code). If you press the Try it out button, set the provider value to GitHub and press the Execute button you will see the results of the call:

Result of sourcecontrol templates call

Troubleshooting

Note that if you get a 403 (Not Authorized) result you need to retrieve the value of the Authorization header again and do the Authorize again as described above.

Discuss on TwitterEdit on GitHub

This work is licensed under a Creative Commons Attribution-NonCommercial 4.0 International License. You are free to share and adapt this work for non-commercial purposes, provided you give appropriate credit, provide a link to the license, and indicate if changes were made. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc/4.0/.

Serge van den Oever's weblog

Serge van den Oever

Personal blog by Serge van den Oever - als je maar lol hebt...
X: @svdoever
LinkedIn: Serge van den Oever - articles on LinkedIn
GitHub: svdoever

Technology Consultant @ Macaw
2021-2024 Sitecore Technology MVP