How to Call External Services in Sitecore Content Hub
Vasiliy Fomichev
In Architecture, Content Hub Posted May 26, 2020
There are many reasons for calling external services, and Content Hub allows us to do it, which adds an enormous amount of flexibility and extensibility to the default functionality. In this article, we will take a look at two ways of calling external APIs.
There two common ways of calling an external API in Sitecore Content Hub – using the API Call action and through a custom script. The difference is pretty straight-forward and clear – if you need to “ping” an external service in an ad-hoc manner, an API Call action is a preferred approach. It works well when calling a simple external service to trigger an action, and that does not require dynamic payload. On the other hand, if you need to create an ETL job, process the result further, or work with dynamic inputs and outputs – a custom script approach would be recommended. Let’s take a look at how to use them.
API Call Action
The API Call action is a turnkey point-and-click solution that does not require any development. A person with limited technical knowledge can do it, which makes this approach attractive for non-technical users, let’s say a Content Hub administrator. Sitecore describes the steps for creating the action in the Sitecore API Call documentation. Remember to create a proper trigger to call the action. Good examples for using this action would include notification API calls, simple communication calls, event-related notifications, and process triggers for external systems.
Custom Script
Anytime we talk about custom scripts in Sitecore Content Hub, we talk about involving a C# developer. While the API Action call is easy to set up and does not require technical knowledge, it is not capable of supporting business processing logic. Once you start needing to extract data from one dynamically, massage it and submit it into another system, API Call actions step aside, and custom scripts come into play. The best part about Content Hub scripts is that it has some of the commonly used C# libraries already pre-loaded.
Tip: Sitecore Content Hub supports loading external libraries and packages from repositories, like NuGet, to be used in scripts.
Although there is plenty of web service calling libraries available, I recommend staying as close as possible to the framework to reduce the upgrade and maintenance costs; thus, I’m including an example of calling an external API using the HttpClient.
using Stylelabs.M.Sdk;
using System.Net;
using System.Net.Http;
using System.Text;
using Newtonsoft.Json;
var someVariable = string.Empty;
Context.PropertyBag.TryGetValue("someVariable", out someVariable);
MClient.Logger.Info($"Loggin the variable: {someVariable}.");
var serviceUrl = $"https://sampledomain.com/api/dothings";
var content = new {someVariable= someVariable};
using (var client = new HttpClient())
{
using (var request = new HttpRequestMessage(HttpMethod.Post, serviceUrl))
{
var json = JsonConvert.SerializeObject(content);
using (var stringContent = new StringContent(json, Encoding.UTF8, "application/json"))
{
request.Content = stringContent;
using (var response = await client.SendAsync(request, HttpCompletionOption.ResponseHeadersRead).ConfigureAwait(false))
{
var message = response.EnsureSuccessStatusCode();
var responseMsg = await message.Content.ReadAsStringAsync();
MClient.Logger.Info($"Log the response: {responseMsg}.");
}
}
Error handling was left out of the example for simplicity; however, it is strongly encouraged. Anytime your code relies on a system out of your control, it should be wrapped with try/catch, and proper handling should be implemented. Also, keep in mind that long-running in-process scripts will degrade users’ experience, thus, either run the script in the background, or use a disconnected architectural approach to avoid holding up the API call response.
WARNING: When NOT to Call External APIs
Architects must be careful not to get carried away with the disconnected architecture, especially in the serverless world. It’s easy to start thinking of Sitecore Content Hub as a platform that isn’t capable of processing on its own and needs all processing to have exported. Although Content Hub is a SaaS solution, it sits on a stack of containers and Azure services and has a decent amount of resources allocated to each instance. Anytime you think about creating an external serverless appliance to handle processing, consider performing that processing inside the Content Hub instance first. Sitecore Content Hub does a good job in allowing to run processing synchronously and in the background, thus, make sure you consider taking advantage of that, because introducing an extra system adds risk, cost, and impacts areas such as performance, and security.
