API Management Policies and Transformation

Azure API Management (APIM) policies are a powerful feature that allows you to change the behavior of your API through configuration rather than code. Policies are a collection of statements that are executed sequentially on the request or response of an API. They are defined in XML format and can be applied at different scopes: global (All APIs), product, API, or operation. The most specific scope wins, and if multiple policies apply, they are combined using a merge strategy.

Policies exist to address cross-cutting concerns that are common across many APIs: authentication, rate limiting, caching, logging, transformation, and validation. Without policies, you would need to implement these features in every backend service, leading to duplication and inconsistency. With APIM policies, you centralize these concerns in the gateway, making it easier to enforce security and governance.

When a request arrives at the APIM gateway, it passes through four policy sections in order:

Each section is a container of policy statements. The order of statements within a section matters. For example, if you have a rate-limit policy and a set-header policy in the inbound section, the rate limit is checked first, then the header is added.

Policies can include expressions written in C# using a subset of .NET Framework types. Expressions are enclosed in @(expression) in the XML. They are evaluated at runtime. For example:

<set-header name="Custom-Header" exists-action="override">
    <value>@(context.Request.Headers.GetValueOrDefault("X-Forwarded-For", ""))</value>
</set-header>

Key objects available in expressions: - context: Provides access to the request, response, API, product, user, and subscription. - context.Request: Contains headers, query parameters, body, URL, method. - context.Response: Contains headers, body, status code. - context.Api: Contains API name, path, service URL. - context.Subscription: Contains subscription key, name, etc.

Rate Limiting:

<rate-limit calls="10" renewal-period="60" />

This limits the number of calls per subscription key to 10 per 60 seconds. If exceeded, returns 429 Too Many Requests.

Quota:

<quota calls="1000" renewal-period="86400" />

Limits total calls per subscription over a 24-hour period.

Validate JWT:

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized">
    <openid-config url="https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration" />
    <required-claims>
        <claim name="aud" match="all">
            <value>api://{client-id}</value>
        </claim>
    </required-claims>
</validate-jwt>

Set Header:

<set-header name="X-Request-ID" exists-action="override">
    <value>@(Guid.NewGuid().ToString())</value>
</set-header>

Set Body:

<set-body template="liquid">
    {
        "name": "{{body.name}}",
        "email": "{{body.email}}"
    }
</set-body>

Supports Liquid templates or inline expressions.

Rewrite URL:

<rewrite-uri template="/api/v2/orders/{orderId}" />

This rewrites the incoming URL before forwarding to the backend.

CORS:

<cors allow-credentials="true">
    <allowed-origins>
        <origin>https://myapp.com</origin>
    </allowed-origins>
    <allowed-methods>
        <method>GET</method>
        <method>POST</method>
    </allowed-methods>
    <allowed-headers>
        <header>*</header>
    </allowed-headers>
</cors>

Policies can be defined at four scopes:

When multiple policies apply, they are combined. The order of evaluation is: Global -> Product -> API -> Operation. For each section (inbound, backend, outbound, on-error), the policies are merged. If two policies set the same header, the more specific scope overrides the less specific one, unless exists-action is set to override or append.

Policy fragments are reusable policy snippets that can be included in multiple policies. They help reduce duplication. For example, you can create a fragment for JWT validation and include it in multiple APIs:

<include fragment="jwt-validate" />

Example:

<inbound>
    <cache-lookup vary-by-developer="false" vary-by-developer-groups="false" downstream-caching-type="none">
        <vary-by-query-parameter>query</vary-by-query-parameter>
    </cache-lookup>
</inbound>
<outbound>
    <cache-store duration="3600" />
</outbound>

On-error policies are triggered when an error occurs. You can use set-variable to capture error details and return-response to return a custom error response.

<on-error>
    <set-variable name="errorMessage" value="@(context.LastError.Message)" />
    <return-response>
        <set-status code="500" reason="Internal Server Error" />
        <set-body>{"error": "@(context.Variables.GetValueOrDefault<string>("errorMessage"))"}</set-body>
    </return-response>
</on-error>

Policies are defined in the Azure portal under each scope (All APIs, Products, APIs, Operations). You can also manage them programmatically via Azure CLI, PowerShell, or ARM templates. To verify policies, use the Test Console in the portal to send requests and inspect the processed request/response.

A large e-commerce company exposes its product catalog and order APIs to third-party developers. The company uses Azure API Management as the gateway. They need to enforce authentication using Azure AD and rate limit each developer subscription to 1000 calls per hour. Additionally, they want to add a correlation ID to every request for tracing. The solution: at the global scope, they add a validate-jwt policy that checks tokens against Azure AD. At the product scope, they add a rate-limit policy with calls="1000" and renewal-period="3600". They also add a set-header policy in the inbound section to add a correlation ID using @(Guid.NewGuid().ToString()). In production, they monitor usage and adjust rate limits based on tier. A common mistake is placing the rate-limit policy before authentication, which can lead to unauthenticated requests consuming quota. The correct order is validate-jwt first, then rate-limit.

A financial institution has a legacy SOAP backend that they want to expose as a RESTful API to mobile clients. They use APIM to transform requests and responses. In the inbound section, they use set-body to convert the incoming JSON request to a SOAP envelope using a Liquid template. They also set the Content-Type header to text/xml. In the outbound section, they use set-body to parse the SOAP response and convert it to JSON. They also handle errors by checking the SOAP fault and returning a standard HTTP error. Performance is critical: body transformations can be CPU-intensive, so they use caching to reduce repeated transformations. They also use the send-request policy to call a transformation service if needed. Misconfiguration often leads to XML parsing errors or missing namespaces. They test extensively with different payloads.

A SaaS provider offers a multi-tenant API where each tenant has custom requirements. They use APIM with policies at the API scope. For each tenant, they create a separate product and assign policies to that product. For example, Tenant A needs IP filtering, while Tenant B needs a custom header. They use policy expressions to read tenant ID from the subscription context and apply conditional logic. They also use policy fragments to share common policies like logging. In production, they have hundreds of tenants, and policy management becomes complex. They use ARM templates to automate policy deployment. A common issue is policy size limit: the total policy XML for an API cannot exceed 64 KB. They break large policies into fragments. They also use the choose policy for conditional branching.