Here we are, ready for another edition of API Management Best Practices, Tips, and Tricks. In my prior blog post, I inaugurated this series by addressing the first best practices, tips, and tricks—How to validate if a Header is an empty string. Today, I will speak about another helpful Best practice, Tips, and Tricks that you must consider while implementing your policies: How to access a context variable on body transformation using liquid.
#2 How to access a context variable on body transformation using liquid
Liquid is an open-source template language created by Shopify and written in Ruby. It is the backbone of Shopify themes and is used to load dynamic content on storefronts.
Azure API Management uses the Liquid templating language (DotLiquid) to transform the body of a request or response. This can be effective if you need to reshape the format of your message completely. That can be accomplished using the set-body policy inside inbound, backend, outbound, or on-error policies. For example:
<inbound>
<base />
…
<set-body template="liquid">
{
"Header": {
"OrigSystem": "API Management",
"DateRequest": "{{body.MsgDate}}"
},
"InputParameters": {
"MyObject": {
"Reference": "{{body.ExtId}}",
"Type": "{{body.ObjType}}",
"Id": "{{body.Id}}"
}
}
}
</set-body>
</inbound>
On the other side, inside API Management policies, users will always have the availability to create context variables or, in this particular case, User-Defined Variables or Policy Variables (whatever you want to call them) to store and manipulate data specific to your API’s needs. These variables are often used in policies to make decisions or modify requests and responses.
Creating or reading a value of a context variable inside an APIM policy is a straightforward operation. Once again, Microsoft documentation will explain that simple operation very well. To declare a context variable and assign it a value, we utilize the set-variable policy, specifying the value through an expression or a string literal. For example:
<set-variable name="myVar" value="Test" />
Or
<set-variable name="mySecondVar" value="@(context.Request.Headers.GetValueOrDefault("MyHeader"))" />
To read a context variable and assign it a value, we utilize the following expression:
(string)context.Variables["myVar"]
Or using the GetValueOrDefault function:
context.Variables.GetValueOrDefault<string>("myVAr", "This is the default value")
What is more difficult is to find a good documentation that explains how to read the value of a context variable on body transformation (set-body policy) using the liquid template. I won’t be wrong to say that 98% of the information I looked up online was wrong because most of them say that is using the same way – (string)context.Variables[“myVar”] – what is incorrect. We should use a dot (.) notation inside the liquid to access the variables, similar to many programming languages used to access properties deep within the structure. So, in this case, we should use the following:
<set-body template="liquid">
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="http://tempuri.org/">
<soapenv:Header />
<soapenv:Body>
<Person>
<name>Sandro Pereira</name>
<description>{{context.Variables.myVar}}</description>
</Person>
<soapenv:Body>
</soapenv:Envelope>
</set-body>
I hope you enjoy this tip and stay tuned for the following Azure API Management Best practices, Tips, and Tricks.
If you liked the content or found it helpful and want to help me write more content, you can buy (or help buy) my son a Star Wars Lego!
