Azure API Management

Enhance, secure, and manage your APIs effortlessly.

Built-in Policies in Azure API Management

Azure API Management provides a set of powerful built-in policies that allow you to configure the behavior of your APIs. These policies are executed in a specific order for each request and response, enabling you to implement cross-cutting concerns like authentication, authorization, rate limiting, transformation, and caching.

Policies are defined within a policy XML document, which can be applied at different scopes: global, product, API, or operation. The effective policy at any given scope is a merge of policies from all applicable parent scopes.

Policy Execution Flow

Policies are executed sequentially within two main execution contexts:

  • Inbound processing: Executed before the request reaches the backend service. This is where you handle tasks like authentication, validation, rate limiting, and request transformation.
  • Outbound processing: Executed after the backend service returns a response but before it's sent to the client. This is where you can transform responses, add headers, or cache content.

Additionally, there are 'backend' and 'on-error' processing contexts.

Common Built-in Policies

Here are some of the most frequently used built-in policies:

set-header

Adds, modifies, or removes a header in the request or response.

<set-header name="X-Powered-By" exists-action="override">
    <value>Azure API Management</value>
</set-header>

set-body

Replaces the request or response body with new content. This is often used for content transformation.

<set-body template="none">
    { "message": "Request processed by APIM" }
</set-body>

set-location

Sets the Location header for HTTP redirects.

<set-location>
    https://example.com/new-resource/{context.Response.Body.id}
</set-location>

set-status

Sets the HTTP status code for the response.

<set-status code="201" reason="Created"/>

send-request

Sends a request to a specified backend service. Useful for performing backend lookups or orchestrating multiple services.

<send-request mode="new" response-variable-name="externalData" timeout="10" ignore-error="false">
    <set-url>https://external.service.com/data?id=@(context.Request.Path.Substring(context.Request.Path.LastIndexOf('/') + 1))</set-url>
    <set-method>GET</set-method>
</send-request>

forward-request

Forwards the original request to the configured backend service.

<forward-request />

choose

A conditional policy that allows executing different policy snippets based on specified conditions.

<choose>
    <when condition="@(context.Request.Headers.GetValueOrDefault("X-Tenant", "") == "premium")">
        <set-header name="X-Premium-Feature" exists-action="override">
            <value>Enabled</value>
        </set-header>
    </when>
    <otherwise>
        <set-header name="X-Premium-Feature" exists-action="delete"/>
    </otherwise>
</choose>

check-header

Checks if a specified header exists in the request.

<check-header name="Authorization" required="true"/>

rate-limit

Limits the number of calls allowed within a specified time window. Crucial for preventing abuse and managing backend load.

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

quota-by-key

Limits the total number of calls allowed for a specific key (e.g., subscription key) over a period.

<quota-by-key calls="10000" renewal-period="2592000" increment-condition="@(true)" counter-key="@(context.SubscriptionKey)" />

validate-content

Validates the request or response body against a JSON schema.

<validate-content template="json-schema" />

validate-parameters

Validates query parameters, path parameters, and headers against their defined schemas.

<validate-parameters />

set-variable

Creates a named variable that can be used by other policies within the same execution context.

<set-variable name="userId" value="@(context.Request.Headers.GetValueOrDefault("X-User-ID", ""))"/>

cache-lookup / cache-store

Policies for implementing response caching to improve performance and reduce backend load.

<cache-lookup vary-by-developer="false" vary-by-key="true" is-front-door="false" cache-key="/@context.Request.Operation.Name">
    <dependencies>
        <dependency id="backend"/>
    </dependencies>
</cache-lookup>

<cache-store duration="60" vary-by-developer="false" vary-by-key="true" cache-key="/@context.Request.Operation.Name"/>

Policy Expressions

Many policies utilize policy expressions (written in C# syntax) to dynamically determine policy behavior based on request/response data, context variables, and custom logic. These expressions are enclosed in @( ... ).

Applying Policies

You can configure policies through the Azure portal, Azure CLI, or Azure PowerShell. The XML editor in the portal provides a user-friendly interface for managing your policy definitions.

Understanding and effectively utilizing these built-in policies is fundamental to harnessing the full power of Azure API Management for your API gateway needs.