Policies in Azure API Management


APIs have become the engines of growth in today’s economy, and are fundamentally changing the way organizations do business.

Azure API management (APIM) helps organizations publish APIs to external partner, and internal developers to unlock the potential of their data and services.

Azure API management is a proxy that sits between your back-end services or APIs, and the calling applications. So, think of this proxy as an intermediate layer, and this intermediate layer sits well with the distributed architecture of the web, where systems are comprised of multiple layers, each layer is made up of HTTP, and each layer provides additional capabilities.

In a nutshell, APIM helps you to

·         Package and publish APIs to developers and partners

·         On-board developers via a self-service portal

·         Ramp-up developers with docs, samples, and API console

·         Build an API façade for existing backend services

·         Reliably protect published APIs from misuse and abuse

·         Gain insights into API usages and health from analytics report

Policies in Azure API Management

In Azure API Management (APIM), policies are a powerful capability of the system that allow you to change the behavior of the API through configuration.

Policies essentially are a bunch of statements, and think of it as a programming language almost, and just like in any programming language you have statements, so does the policy definition have statements.

Popular Statements include format conversion from XML to JSON and call rate limiting to restrict the amount of incoming calls from a developer.

azure api management

Refer the below Azure documentation link for the entire list of policies available.

Policy Configuration

The policy definition is a simple XML document that describes a sequence of inbound and outbound statements.

The configuration is divided into inboundbackendoutbound, and on-error.

azure api management

Much like a C# snippet, you can place policy statement in any of these sections.

You can place your policy snippet or the statements inside the inbound section, and by doing so, these statements will be applied to the incoming request.

You can place the snippet inside the back-end section, and in this case, all the statements that make up that snippet will get applied just before the request is forwarded to the back-end.

You can also place your policy statements inside the outbound section, and once again as the name suggests, these statements will be applied to the response before it has returned to the caller.

And if an error is encountered while executing statements in any of these sections, the statement within the on-error section will get executed, so think of this as your try-catch block if you will.

Azure Policy Expressions

Policy expressions are well-formed, C# 7.0 expressions.

You can see some examples below, it can be a single statement @ sign within parentheses, or it can be a collection of statements, @ sign within curly braces. The only requirement is that every code path ends in a return statement. 

azure api management

Furthermore, each expression can have access to something called a context, and this context provides information about incoming requests. So, you can access this information about the incoming request in a read-only manner, and make some interesting decisions based on that.

In addition to the context, all expressions have access to a subset of the .NET framework, and you can go through the documentation and look at all the .NET types that are available. But as you can see here, the expressions become powerful, they are nothing but C# snippets.

You have access to the context, you have access to many .NET types, and combine these two, you can write some logic, which is then compiled using the Roslyn compiler, and then inject it into the flow as your calls are coming from your end users, and being directed to the back-end API.

Creating Azure Policies

Now that we discuss about the policy concept, configuration file and the various section, it’s now time to put this knowledge into action.

We would create couple of policies in this section.

Here I have used a sample product API, hosted in Azure. Swagger UI for product API is shown below

azure api management

This is a very basic API for CURD operation of a product item.

We would need the swagger json file to add/import product API in Azure API management. To get the swagger file you need to append “/swagger/docs/v1” in your API end point (Example:

Save the swagger document as json file.

azure api management

Now create an instance of API Management and then import the API by selecting “OpenAPI Specification” tile as shown below.

azure api management

Select the Swagger file which we have created before. Fill in the required details – Display name, Name, API URL suffix and Product and click on Create.

azure api management

Now you have new API (Sample Product API) created in API Management. You have all the operations and different sections – Front endInbound ProcessingBackend, and Outbound Processing.

azure api management

To quickly test this new API, click on Test tab à select Product_Get à click on Send button.

azure api management

You should see the response as shown below. This is the response from your backend API (in this case it would be product API)

Rate Limit Policy

Now let’s add protection for your backend API by configuring rate limits.

Select Design tab and then in the Inbound processing window, click the triangle (next to the pencil)  and select Code editor as shown below.

azure api management

Position the cursor inside the element. In the right window, under Access restriction policies, click + Limit call rate per key

azure api management

Modify your <rate-limit-by-key code (in the element) to the following code:

<rate-limit-by-key calls=”3″ renewal-period=”30″ counter-key=”@(context.Subscription.Id)” />

I need to specify the number of calls that I want to restrict to, and I need to specify a renewal period. So if you look at this policy statement, what this really means is that I’m only allowing the caller to make 3 calls within the period of 30 seconds.

azure api management

Now save the policy and you should see the rate-limit-by-key policy policy in Inbound section policy as shown below.

azure api management

Let’s test this API with the Postman tool. You need to copy the Request URL and Ocp-Apim-Subscription-Key from the Test tab as shown below.

azure api management

In postman, you should be get the successful response for the first 3 time within 30 seconds.

But as soon as you cross the limit of 3 calls within 30 seconds, you would get status code 429 with message – “Rate limit is exceeded. Try again in 28 seconds.” 

azure api management

So this concludes our first policy, applying a rate limit, and the code of policies exactly the same, except instead of rate limit, you’re applying a total number of calls or total number of bandwidth for a renewal period again.

JSON to XML Policy

Next policy that we want to talk about is a policy statement that returns the caller XML instead of JSON, and even if my Product API as you know has been returning a JSON, this policy statement is going to take the JSON and convert that into an XML and return it back to the caller.

Select Design tab and then in the Outbound processing window, click the triangle (next to the pencil) and select Code editor as shown below.

azure api management

Position the cursor inside the <outbound> element. In the right window, under Transformation policies, click + Convert JSON to XML

azure api management

Modify your <json-to-xml code (in the element) to the following code:

azure api management

The first attribute is an apply attribute, and it can be set to always. In this case, I’m saying irrespective of the fact that the content-type is JSON or not, I want this conversion to take place. The second attribute is should I be paying attention to a request header, has the JSON conversion or the XML conversion been requested or not? In this case, I’m going to say false, so I’m not going to pay attention to the accept header, and I always want this policy statement to be applied.

Now save the policy and you should see the json-to-xml policy policy in Outbound section policy as shown below.

azure api management

To test it, go back to postman tool and try now. You should see the XML response now.

azure api management

So, this concludes the demonstration for the second policy, which was JSON to XML policy.


In Azure API Management (APIM), policies are a powerful capability of the system that allow you to change the behavior of the API through configuration.

You can apply the policy inside inbound section, back-end section, outbound section and on-error section. We created two policies in a sample product API

·         Rate limit policy in inbound section

·         JSON to XML in outbound section

Related Posts

Copilot Studio

June 1, 2024

Microsoft Build 2024: A Look at the Important Announcements

Let’s dive deeper and explore the key takeaways from Microsoft Build 2024! We’ll cover the key updates to Microsoft Copilot Studio and Power Platform in this blog.

Microsoft Snowflake Partnership

May 31, 2024

Microsoft and Snowflake: New Partnerships For Seamless Data Experience!

Microsoft announced its expansion to their partnership with Snowflake during the Build Conference 2024. This collaboration promises to revolutionize data management by offering seamless bi-directional data access and a commitment to open standards. OneLake, the cornerstone of Fabric, shines even brighter with this partnership. As a single, unified, Software-as-a-Service (SaaS) open data foundation, OneLake empowers