Tutorial: Transform and protect your API

APPLIES TO: All API Management tiers

In this tutorial, you learn about configuring policies to protect or transform your API. Policies are a collection of statements that are run sequentially on the request or response of an API that modify the API's behavior.

For example, you might want to set a custom response header. Or, protect your backend API by configuring a rate limit policy, so that the API isn't overused by developers. These examples are a simple introduction to API Management policies. For more policy options, see API Management policies.

In this tutorial, you learn how to:

• Learn the Azure API Management terminology.
• Understand the concept of policies in Azure API Management.
• Complete the following quickstart: Create an Azure API Management instance.
• Also, complete the following tutorial: Import and publish your first API.

1. In the Azure portal, search for and select API Management services.

   

2. On the API Management services page, select your API Management instance.

   

To see the original response:

1. In your API Management service instance, select APIs.
2. Select Swagger Petstore from your API list.
3. Select the Test tab, on the top of the screen.
4. Select the GET Finds pets by status operation, and optionally select a different value of the status Query parameter. Select Send.

The original API response should look similar to the following response:

API Management includes several transformation policies that you can use to modify request or response payloads, headers, or status codes. In this example, you set a custom response header in the API response.

This section shows you how to configure a custom response header using the set-header policy. Here you use a form-based policy editor that simplifies the policy configuration.

1. Select Swagger Petstore > Design > All operations.

2. In the Outbound processing section, select + Add policy.

   

3. In the Add outbound policy window, select Set headers.

   

4. To configure the Set headers policy, do the following:

   1. Under Name, enter Custom.
   2. Under Value, select + Add value. Enter "My custom value".
   3. Select Save.

5. After configuration, a set-header policy element appears in the Outbound processing section.

   

This section shows how to add protection to your backend API by configuring rate limits, so that the API isn't overused by developers. This example shows how to configure the rate-limit-by-key policy using the code editor. In this example, the limit is set to three calls per 15 seconds. After 15 seconds, a developer can retry calling the API.

1. Select Swagger Petstore > Design > All operations.

2. In the Inbound processing section, select the code editor (</>) icon.

   

3. Position the cursor inside the <inbound> element on a blank line. Then, select Show snippets at the top-right corner of the screen.

   

4. In the right window, under Access restriction policies, select Limit call rate per key.

   The <rate-limit-by-key /> element is added at the cursor.

   

5. Modify your <rate-limit-by-key /> code in the <inbound> element to the following code. Then select Save.

   <rate-limit-by-key calls="3" renewal-period="15" counter-key="@(context.Subscription.Id)" />
   

At this point, if you look at the code in the code editor, your policies look like the following code:

<policies>
     <inbound>
         <rate-limit calls="3" renewal-period="15" counter-key="@(context.Subscription.Id)" />
         <base />
     </inbound>
     <outbound>
         <set-header name="Custom" exists-action="override">
             <value>"My custom value"</value>
           </set-header>
         <base />
     </outbound>
     <on-error>
         <base />
     </on-error>
 </policies>

The rest of this section tests policy transformations that you set in this article.

1. Select Swagger Petstore > Test.

2. Select the GET Finds pets by status operation, and optionally select a different value of the status Query parameter. Select Send.

   As you can see, the custom response header is added:

   

1. Select Swagger Petstore > Test.

2. Select the GET Finds Pets by Status operation. Select Send several times in a row.

   After sending too many requests in the configured period, you get the 429 Too Many Requests response.

   

3. Wait for 15 seconds or more and then select Send again. This time you should get a 200 OK response.

In this tutorial, you learned how to:

Advance to the next tutorial: