Introduction:
In the ever-evolving landscape of API development, dealing with legacy systems and formats is a common challenge. This blog post aims to assist you in leveraging Azure API Management (APIM) to address a specific scenario: transforming XML data to JSON and vice versa. We'll delve into the techniques supported by Azure API Management that allow you to bridge the gap between these formats seamlessly.
Understanding the Challenge:
Legacy systems often communicate using XML, while modern APIs tend to rely on JSON due to its simplicity and widespread support. In scenarios where your API needs to interact with both formats, a transformation mechanism becomes crucial. Azure API Management can be the solution to ensure a smooth transition between XML and JSON.
This scenario can occur even with your own system. Imagine that you have a legacy application that uses XML standards for integration. To modernize your application, you can explore the option to migrate your backend to JSON standards first and explore the power of Azure API Management to transform your data between frontend and backend. This will give you the ability to modernize your app in chunks.
First things first:
After importing your backend API specs into Azure API Management*, we have a huge set of features we can explore and how to for example: Centralized authentication, CORS policy, quota and rate limits, correlation driven diagnostics, developer tools and much more (link at the end about all the capabilities of Azure API Management).
In this blog post, I will assume that you already have a basic understanding of using Azure API Management and already imported APIs. After importing an API, we can choose to set policy for All operations or for a specific operation listed as shown below:
After clicking the policy icon </> or the "+ Add Policy" button, you can either code your policy from the scratch or choose some existing template that will help you configure your policy. If you choose the code option the editor will appear on your screen and you can define your policy by coding it:
Sometimes we will need more control or more specific adjustment on a policy and then the code will be very handful for it. And we also can explore the use of an official extension for VSCode* that we can connect with our API Management instance and update our policies.
* Import your API specs into Azure API Management: https://learn.microsoft.com/en-us/azure/api-management/import-api-from-oas
* VSCode API Management extension: https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-apimanagement
Converting XML Requests in JSON:
1. Request Transformation Policies:
Azure API Management offers powerful policy-based transformations that allow you to modify incoming and outgoing requests and responses automatically. Let's take a look on the <inbound> structure on how convert XML requests to JSON.
<inbound>
<base />
<xml-to-json kind="direct" apply="always" consider-accept-header="false" />
</inbound>
<backend>
<base />
</backend>
<outbound>
<base />
</outbound>
<on-error>
<base />
</on-error>
Using the <xml-to-json> policy you can convert the XML provided on the request to pass into backend already converted into JSON.
Refer: https://learn.microsoft.com/en-us/azure/api-management/xml-to-json-policy
2. Coding what you need:
How about having more control over what you want to extract from the XML? Or even to make small transformations on the obtained data, you can explore the use of code snippets for this specific task as shown in the code-snipet below:
<inbound>
<base />
<xml-to-json kind="direct" apply="always" consider-accept-header="false" />
<set-body>@{
JObject inBody = context.Request.Body.As<JObject>();
var id = (int)inBody.SelectToken("soapenv$Envelope.soapenv$Body.Id");
var name = "Name: " + (string)inBody.SelectToken("soapenv$Envelope.soapenv$Body.Name");
var address = (int)inBody.SelectToken("soapenv$Envelope.soapenv$Body.Address");
JObject outBody = new JObject();
outBody.Add(new JProperty("Id", id));
outBody.Add(new JProperty("Name", name));
outBody.Add(new JProperty("Address", address));
return outBody.ToString();
}</set-body>
</inbound>
<backend>
<base />
</backend>
<outbound>
<base />
</outbound>
<on-error>
<base />
</on-error>
3. Liquid Template for quick transformations:
Exploring the use of Liquid Template can also be handful to generate XML to JSON data and it's very useful to get a quick transformation without any extra-work:
<inbound>
<base />
<set-body template="liquid">
{
"Customer": {
"Id" : "{{content.Envelope.Body.Id}}",
"Name" : "{{content.Envelope.Body.Name}}",
"Address" : "{{content.Envelope.Body.Address}}"
}
}
</set-body>
</inbound>
<backend>
<base />
</backend>
<outbound>
<base />
</outbound>
<on-error>
<base />
</on-error>
Converting JSON Responses in XML:
Once the backend has processed all the information and responded to your request, you can basically use the same approach we use for requests. But now we'll use the <outbound> tag in our policy to do the necessary transformations. Remember that you can use these same 3 (three) examples we used in the previous section:
1. <json-to-xml> attibute: https://learn.microsoft.com/en-us/azure/api-management/json-to-xml-policy
2. Coding
3. Liquid Templates.
Conclusion:
Azure API Management provides a comprehensive solution for handling legacy scenarios involving XML and JSON transformations. Whether you need to convert XML requests to JSON or JSON responses to XML, APIM's versatile policy system and support for Liquid templates offer the necessary tools to achieve seamless data interchange. By following the techniques outlined in this post, developers can bridge the gap between these formats and ensure efficient communication between modern APIs and legacy systems.
Remember, while these power features are valuable, considering a more long-term approach to migrate legacy systems to JSON can simplify your architecture and improve efficiency.
Have you encountered scenarios involving XML and JSON transformations in APIM? Share your experiences and insights with us in the comments below.
If you want know and explore more features on Azure API Management, follow the link bellow:
Happy coding!