Here we are, ready for another edition of API Management Best Practices, Tips, and Tricks. In the previous post, I kicked off the series by showing how to validate whether a header is empty.
Today, I’ll focus on another useful best practice you should consider when building policies: how to access a context variable during body transformation using Liquid.
📝 One-Minute Brief
Accessing context variables during body transformations is not straightforward in Azure API Management. This article explains how to correctly read policy variables inside set-body transformations using Liquid templates, clarifying common misconceptions and providing a reliable pattern for real‑world APIM scenarios.
#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. Shopify themes rely on it to load dynamic content on storefronts.
Azure API Management uses the Liquid templating language (DotLiquid) to transform request and response bodies. This approach works well when you need to fully reshape a message. You can achieve this by using the set-body policy in inbound, backend, outbound, or on‑error sections. 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 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 use the same way – (string)context.Variables[“myVar”] – which is incorrect. We should use a dot (.) notation within the liquid to access variables, similar to how many programming languages use to access properties deep within a 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, you can buy (or help buy) my son a Star Wars Lego set!
