Policies are an API Management capability that allows you to change the behavior of your exposed API using a configuration file and without changing your application code.
Policies can be defined on all the APIs of your API Management instance, on a single API, or on a single operation in an API, and finally, you can also add policies to a single product. Policies are a set of statements you can apply to an API request (before the request is routed to the backend services) or to the response (before the response is returned to the caller).
Using policies, you can authenticate the request, implement restriction policies (for example, set a usage quota for a subscription or limit the number of calls for a product), implement caching, rewrite the URL, transform a request or response payload from JSON to XML, and so on.
You can display the policies applied to a single API operation simply by selecting the APIs option in the API Management blade and the single API in the corresponding list, as shown in the following screenshot:
As you can see in the preceding screenshot, in the design area, you have four sections that you can configure:
- Frontend: In this section, you can configure how the API is exposed to developers. You can change the HTTP verb, the URL, the description, and so on. Here, you can also modify the OpenAPI specification for the API:
- Inbound processing: Here, you can configure the policies applied to the request.
- Backend: Here, you can add policies that are executed immediately before API Management calls the backend service and configures the backend service itself (for example, the Azure resource you are using, or the HTTP URL of your on-premises web service).
- Outbound processing: Here, you can configure the policies applied to the response before it is sent to the caller.
Behind the scenes, the policies are described in an XML file:
<policies>
<inbound>
<base />
<set-backend-service id="apim-generated-policy" backend-id="masterservdevsite" />
</inbound>
<backend>
<base />
</backend>
<outbound>
<base />
</outbound>
<on-error>
<base />
</on-error>
</policies>
As you can see in the previous XML snippet, you have an on-error section you can use to manage what happened if there is an error during an API call.
You can define the order in which the policies are evaluated simply by moving the policy XML tags that define them. The API Management policies engine will evaluate the policies starting from the top ones.
You can define policies in relation to products: all API; single API; or single operation level; and the <base /> tag tells the API Management policy engine to apply the policies present in the level that is immediately higher.
The order in which API Management evaluates policies is as follows:
- Global (all the APIs of your API Management instance)
- Product
- Single API
- Single operation
In the previous snippet, for example, when the API Management policies engine evaluates the inbound policies, it first applies the Get Version API policies, and then applies the <set-backend-service /> policy.
To add a new policy, for example, at a single operation level, you can modify the XML file manually, or you can use the + Add policy button you can find in the Inbound processing and Outbound processing sections.
For example, you can add a caching feature to your API simply by choosing the cache-lookup/store policy:
Every policy has its configuration form with different parameters that you can set. In the previous sample, you set a cache timeout at 60 seconds and set a cache for each developer (identified by its subscription keys):
When you save the policy, the Azure portal modifies the XML file:
<policies>
<inbound>
<base />
<set-backend-service id="apim-generated-policy" backend-id="masterservdevsite" />
<cache-lookup vary-by-developer="true" vary-by-developer-groups="false" downstream-caching-type="none" />
</inbound>
...
<outbound>
<base />
<cache-store duration="60" />
</outbound>
...
</policies>
As you can see in the previous code snippet, the caching policy is composed of two single entries in the XML file:
- Cache lookup: This policy works on the request and looks for the response stored in the cache (for every developer using their subscription keys).
- Cache store: This policy works on the response and stores the response itself for the developer.