To communicate with APIs, the message format generally used by Microsoft BizTalk Server is XML or Json. There are indeed some native pipeline components which allows us, while both sending and receiving, to convert from XML to Json and from Json to XML as well: the Json encoder & decoder.
However, the GraphQL query language is more and more used by APIs. The goal of this article is therefore to show a way to communicate from BizTalk to an API in GraphQL.
The first step is to generate the Json equivalent of the GraphQL request we want to send. To achieve that, I use Insomnia. Here is an example of a GraphQL request. Its goal is to get an ID from an order reference:
{ order(ref: "XXX") { fulfilments { edges { node { id } } } }}
To switch the format from GraphQL to Json in Insomnia:
The equivalent message generated is the following:
{"query":"{ order(ref: \"XXX\") { fulfilments { edges { node { id } } } }}"}
We have now to create this message in BizTalk. To do that, several options:
To decide here, we have to consider which flexibility we want. With the helper, the structure of the request – and particularly the name of the fields – is entirely customizable. Note that we can do that with a full xsl map as well.
In this example we use a helper. Taking in account escape characters, here is the content of the message construct shape with the order reference as a predefined variable:
msgIdRequest = new System.Xml.XmlDocument(); Helper.LoadXLANGMsgFromString("{\"query\":\"{ order(ref: " + OrderReference + ") { fulfilments { edges { node { id } } } }}\"}", msgIdRequest);
And in the helper:
public static void LoadXLANGMsgFromString(string source, XLANGMessage dest) { var bytes = Encoding.UTF8.GetBytes(source); using (MemoryStream ms = new MemoryStream(bytes, 0, bytes.Length, false, true)) { dest[0].LoadFrom(ms); } }
Here the role of the helper is only to generate a XLANG message from a string. But it could be used to contain a more complex logic for the request creation, based on parameters passed from the orchestration for instance.
In regards to the bindings, we set a send pipeline PassThruTransmit. In reception, a pipeline containing a Json decoder and a XML Disassembler will allow us to parse the response message (a xsd must first be defined) and finally to get the ID that we want using a xpath request for example.