API Management Policies

Policies in Azure API Management are a powerful feature that allow you to modify and enhance the behavior of your APIs. They are executed on the API gateway, providing a centralized place to implement cross-cutting concerns such as authentication, authorization, rate limiting, transformation, and caching.

Policies are defined as a set of statements that are executed sequentially for an incoming request and outgoing response. You can apply policies at different scopes: global, product, API, or operation level. This allows for fine-grained control over how your APIs behave.

Understanding Policy Expressions

Policy statements use an XML-based syntax and can incorporate policy expressions. These expressions allow you to dynamically evaluate values during policy execution, enabling conditional logic and data manipulation.

Common Policy Sections

Policies are typically structured within the following sections:

inbound: Policies in this section are executed when a request arrives at the API gateway before it is forwarded to the backend service. This is where you'll commonly implement authentication, authorization, rate limiting, and request transformation.
backend: Policies in this section are executed on the way to the backend service. This is less common but can be used for specific backend-related adjustments.
outbound: Policies in this section are executed after the backend service has responded and before the response is sent back to the caller. This is used for response transformation, adding headers, or modifying the payload.
onerror: Policies in this section are executed if any of the policies in the inbound, backend, or outbound sections encounter an error.

Key Policy Examples

1. Validate JWT (Inbound)

This policy validates a JSON Web Token (JWT) passed in the Authorization header of the request.

<policies>
    <inbound>
        <validate-jwt header-name="Authorization"
                       failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
            <audiences>
                <audience>https://api.contoso.com</audience>
            </audiences>
            <issuers>
                <issuer>https://sts.windows.net/YOUR-TENANT-ID/</issuer>
            </issuers>
        </validate-jwt>
        <base />
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <onerror>
        <base />
    </onerror>
</policies>

2. Rate Limiting (Inbound)

This policy limits the number of requests a subscriber can make within a specified time period.

<policies>
    <inbound>
        <rate-limit calls="100" renewal-period="60" counter-key="@(context.Subscription.Id)" />
        <base />
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <onerror>
        <base />
    </onerror>
</policies>

3. Set Backend Service URL (Inbound)

Dynamically set the backend service URL based on request parameters.

<policies>
    <inbound>
        <set-backend-service base-url="@{
            if (context.Request.Url.Query.Contains("version=2")) {
                return "https://api.contoso.com/v2";
            } else {
                return "https://api.contoso.com/v1";
            }
        }" />
        <base />
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <onerror>
        <base />
    </onerror>
</policies>

4. Transform XML to JSON (Outbound)

Convert an XML response from the backend to JSON.

<policies>
    <inbound>
        <base />
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <xml-to-json xpath-expression="@(body)" />
        <base />
    </outbound>
    <onerror>
        <base />
    </onerror>
</policies>

Policy Scopes

Policies can be applied at various levels:

Global level: Applied to all APIs managed by the instance.
Product level: Applied to all APIs within a specific product.
API level: Applied to a specific API.
Operation level: Applied to a specific operation (HTTP method and path) within an API.

The effective policy for a request is a combination of policies applied at all relevant scopes, with the more specific scopes (operation, API) overriding or extending the broader ones.

Important Considerations

When designing your policies, consider the following:

Performance Impact: Complex policies can add latency to your API responses. Optimize your policy logic.
Error Handling: Implement robust error handling using the onerror section.
Security: Policies are a critical part of securing your APIs. Use them to enforce authentication, authorization, and prevent common attacks.
Order of Execution: The order of statements within a policy section matters.

Azure API Management Policies