Policy Expressions in Azure API Management

Azure API Management offers the ability to control and modify the behavior of published APIs using out-of-the-box policies that can be configured from the Publisher portal. These policies are applied to the inbound request or the outbound response in the API Management proxy that sits between the API consumer and the API backend.

Policy expressions augment the ability of API Management policies, providing a sophisticated means to control traffic and modify API behavior without requiring you to write any code or modifying any backend services. You can use policy expressions as attribute values or text values in most API Management policies.

Syntax

Policy expressions use the C# 6.0 syntax and have access to a subset of the .NET Framework types. They also have access to an implicit context variable whose members have information about the request and/or the response.

For instance,  in the Set Variable policy, you can use  a policy expression to set the value as:

The policy expression in the above statement is encapsulated as “@(expression)”, where expressionis a well-formed C# statement. This expression will evaluate as true if the request originates from an iPad or an iPhone client. Here, the context variable provides access to the Request object, whose member Headers provides access to the headers included in the request by the application invoking the API. Note you can’t have a mix of normal text and expressions as a parameter value in a policy.

Multi-statement expressions have to be encapsulated in curly-braces as”@{expression 1; expression 2}”.  All paths in a multi-statement expression must return a value that can be used by the policy.

Orchestration and API Redirection

Policy expressions when used in conjunction with API Management advanced policies to orchestrate sophisticated API re-direction and behavior updates. You can use this to project a modern, updated façade for your published API without rewriting the backend services.

Here’s another example of a policy expression, that when used in the inbound path can be used to redirect an incoming request based on version information included as a query parameter in a published API:

Context in policy expressions

The implicitly-available context variable provides access to the request and/or response parameter of the API call. In addition to the request and response, context also provides access to information about your API Management service instance, such as the published APIs, operations, products, users, subscriptions and variables.

Note that the contents of the context variable can change in each stage of the pipeline. For instance, context.Request.Url will contain the transformed URL after the Rewrite URL policy has been executed.

You can use the Set Variable policy in conjunction with policy expressions to preserve the current contents of an object in the context variable for later use, as below:

\n    ";
      str += context.Request.Method;
      str += " \"";
      str += context.Variables.GetValueOrDefault("requestPath");
      str += "\"";
      return str;
    }" />

The above policy snippet inserts the method & URL path that was used to invoke the original request into the “” section of the response body as the “” element. Since the policy definition uses XML, the characters ‘<‘ and ‘>’ are escaped in the from parameter, but not in the multi-statement policy expression in the to parameter. In this example, we use set-variable to save the request URL path from the context and then use this in the find-and-replace policy.

For a short tutorial on this, see the screencast on Policy Expressions on Channel 9.

To learn more, visit Policies in Azure API Management.