Azure API Management Policies: A Comprehensive Tutorial

Welcome to this in-depth tutorial on Azure API Management (APIM) policies. Policies are the most powerful feature of API Management, allowing you to modify the behavior of your APIs through their request and response pipelines. You can use policies to implement various cross-cutting concerns such as authentication, authorization, rate limiting, transformation, and more.

This tutorial covers essential policy concepts and practical examples. Ensure you have an Azure API Management instance created before proceeding.

What are API Management Policies?

Policies are a collection of statements that are executed sequentially within an API request or response. They are defined in XML within the APIM portal. Each policy has a name and a set of elements that perform specific actions. Policies can be applied at different scopes:

  • Global scope: Applies to all APIs in the API Management instance.
  • Product scope: Applies to all APIs within a specific product.
  • API scope: Applies to a specific API.
  • Operation scope: Applies to a specific operation within an API.

Common Policy Scenarios and Examples

1. Rate Limiting

Control the number of requests an API consumer can make within a given time period. This prevents abuse and ensures fair usage.

<policies>
    <inbound>
        <rate-limit calls="100" renewal-period="60" counter-key="@(context.Request.IpAddress)" />
        <base />
    </inbound>
</policies>

In this example, a consumer is limited to 100 calls every 60 seconds, identified by their IP address.

2. Authentication and Authorization

Implement basic authentication using a subscription key or a JSON Web Token (JWT).

Subscription Key Validation
<policies>
    <inbound>
        <check-header name="Ocp-Apim-Subscription-Key" failed-validation-error-message="Missing Subscription Key." ignore-case="false">
            <-- You can also validate against a list of allowed keys or a specific key -->
        </check-header>
        <validate-subscription key-parameter-name="Ocp-Apim-Subscription-Key" />
        <base />
    </inbound>
</policies>
JWT Validation
<policies>
    <inbound>
        <validate-jwt header-name="Authorization"
                       failed-validation-error-message="Invalid or missing JWT token."
                       required="true">
            <audience value="your-audience-value" />
            <issuer value="your-issuer-value" />
            <credential jwks-url="https://your-aad-tenant.b2clogin.com/your-tenant-id/discovery/v2.0/keys" />
        </validate-jwt>
        <base />
    </inbound>
</policies>

3. Request/Response Transformation

Modify the request or response body, headers, or query parameters.

Adding a Header
<policies>
    <inbound>
        <set-header name="X-Powered-By" exists-action="override">
            <value>Azure API Management</value>
        </set-header>
        <base />
    </inbound>
</policies>
Transforming Request Body (e.g., JSON to XML)
<policies>
    <inbound>
        <rewrite-uri template="/api/v2/{operationName}" />
        <set-body template="liquid">
            {
                "oldKey": "{{context.Request.Body.oldValue}}"
            }
        </set-body>
        <base />
    </inbound>
</policies>

4. Caching

Cache API responses to reduce latency and load on the backend service.

<policies>
    <cache-lookup vary-by-developer="false" vary-by-key="true" default-duration="20" />
    <inbound>
        <base />
        <cache-unless condition="@(context.Response.StatusCode >= 400)" />
    </inbound>
    <backend>
        <base />
        <cache-store duration="60" />
    </backend>
</policies>

Policy Expressions and Context Variables

Policies use expressions that can access context variables. Key context variables include:

  • context.Request: Information about the incoming request (headers, body, URL, etc.).
  • context.Response: Information about the outgoing response.
  • context.Variables: Custom variables you can set and retrieve.
  • context.Deployment: Information about the APIM deployment.

You can use C#-like syntax within policy expressions, often enclosed in @(...).

Advanced Concepts

  • Named Values: Store reusable values (secrets, URLs, etc.) that can be referenced in policies.
  • Custom Policies: Develop custom policy snippets for complex logic.
  • Policy Fragments: Share policy logic across multiple APIs and operations.
  • Conditional Policies: Use <choose> and <when> elements for conditional execution.

Example of Conditional Logic

<policies>
    <inbound>
        <choose>
            <when condition="@(context.Request.Headers.GetValueOrDefault("X-Version", "") == "v2")">
                <set-backend-service base-url="https://api.example.com/v2/" />
            </when>
            <otherwise>
                <set-backend-service base-url="https://api.example.com/v1/" />
            </otherwise>
        </choose>
        <base />
    </inbound>
</policies>

Next Steps

Explore the official Azure API Management policy documentation for a complete reference and more advanced examples. Practice applying different policies to your APIs to understand their impact.