draft complete

Author: gitName

articles/api-management/media/transform-api/api-management-console-new.png

@@ -6,26 +6,26 @@ author: dlepow
 ms.service: azure-api-management
 ms.custom: mvc, devdivchpfy22
 ms.topic: tutorial
-ms.date: 11/18/2024
+ms.date: 11/25/2024
 ms.author: danlep
 ---
 
 # Tutorial: Transform and protect your API
 
 [!INCLUDE [api-management-availability-all-tiers](../../includes/api-management-availability-all-tiers.md)]
 
-In this tutorial, you learn about configuring [policies](api-management-howto-policies.md) to protect or transform your API. For example, protect your backend API by configuring a rate limit policy, so that the API isn't overused by developers. You might want to transform your API so it doesn't reveal private backend info or other potentially sensitive information, or to set a custom header.
+In this tutorial, you learn about configuring [policies](api-management-howto-policies.md) 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 more policy options, see [API Management policies](api-management-policies.md).
+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 just an introduction to to API Management policies. For more policy options, see [API Management policies](api-management-policies.md).
 
 > [!NOTE]
 > By default, API Management configures a global [`forward-request`](forward-request-policy.md) policy. The `forward-request` policy is needed for the gateway to complete a request to a backend service.
 
 In this tutorial, you learn how to:
 
 > [!div class="checklist"]
-> * Protect an API by adding a rate limit policy (throttling)
 > * Transform an API to set a custom response header
+> * Protect an API by adding a rate limit policy (throttling)
 > * Test the transformations
 
 :::image type="content" source="media/transform-api/api-management-console-new.png" lightbox="media/transform-api/api-management-console-new.png" alt-text="Screenshot of API Management policies in the portal.":::
@@ -34,7 +34,7 @@ In this tutorial, you learn how to:
 
 * Learn the [Azure API Management terminology](api-management-terminology.md).
 * Understand the [concept of policies in Azure API Management](api-management-howto-policies.md).
-* Complete the following quickstart: [Create an Azure API Management instance](get-started-create-service-instance.md). For this tutorial, we recommend the Developer tier or the Basic v2 tier. The Consumption tier doesn't support all policies used in this tutorial.
+* Complete the following quickstart: [Create an Azure API Management instance](get-started-create-service-instance.md). For this tutorial, we recommend that you use one of the classic or v2 tiers, for example, the Developer tier or the Basic v2 tier. The Consumption tier doesn't support all policies used in this tutorial.
 * Also, complete the following tutorial: [Import and publish your first API](import-and-publish.md).
 
 [!INCLUDE [api-management-navigate-to-instance.md](../../includes/api-management-navigate-to-instance.md)]
@@ -46,23 +46,47 @@ To see the original response:
 1. In your API Management service instance, select **APIs**.
 1. Select **Swagger Petstore** from your API list.
 1. Select the **Test** tab, on the top of the screen.
-1. Select the **GetSpeakers** operation, and then select **Send**.
+1. 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:
 
 :::image type="content" source="media/transform-api/test-original-response-new.png" lightbox="media/transform-api/test-original-response-new.png" alt-text="Screenshot of the original API response in the portal.":::
 
-As you can see, the response includes the **X-AspNet-Version** and **X-Powered-By** headers.
+## Transform an API to add a custom response header
+
+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.
+
+### Set the transformation policy
+
+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**.
+1. In the **Outbound processing** section, select **+ Add policy**.
+
+   :::image type="content" source="media/transform-api/outbound-policy-small.png" alt-text="Screenshot of navigating to outbound policy in the portal." lightbox="media/transform-api/outbound-policy.png":::
+
+1. In the **Add outbound policy** window, select **Set headers**.
+
+   :::image type="content" source="media/transform-api/set-http-header.png" alt-text="Screenshot of configuring the Set headers policy in the portal.":::
+
+1. To configure the Set headers policy, do the following:
+    1. Under **Name**, enter **Custom**.
+    1. Under **Value**, select **+ Add value**. Enter *"My custom value"*.
+    1. Select **Save**.
+  
+1. After configuration, a **set-header** policy element appears in the **Outbound processing** section.
+
+   :::image type="content" source="media/transform-api/set-policy.png" alt-text="Screenshot of the Set headers outbound policies in the portal.":::
 
 
 ## Protect an API by adding rate limit policy (throttling)
 
-This section shows how to add protection to your backend API by configuring rate limits, so that the API isn't overused by developers. In this example, the limit is set to three calls per 15 seconds. After 15 seconds, a developer can retry calling an API.
+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 tge API.
 
 > [!NOTE]
-> This example shows how to configure the `rate-limit-by-key` policy using the code editor. This policy isn't supported in the Consumption tier.
+> This policy isn't supported in the Consumption tier.
 
-1. Select **Petstore API** > **Design** > **All operations**.
+1. Select **Swagger Petstore** > **Design** > **All operations**.
 1. In the **Inbound processing** section, select the code editor (**</>**) icon.
 
    :::image type="content" source="media/transform-api/inbound-policy-code.png" lightbox="media/transform-api/inbound-policy-code.png" alt-text="Screenshot of navigating to inbound policy code editor in the portal.":::
@@ -79,92 +103,51 @@ This section shows how to add protection to your backend API by configuring rate
 
 1. Modify your **`<rate-limit-by-key />`** code in the  **`<inbound>`** element to the following code. Then select **Save**.
 
-    ```
+    ```xml
     <rate-limit-by-key calls="3" renewal-period="15" counter-key="@(context.Subscription.Id)" />
     ```
 
 
-## Transform an API to add a custom response header
-
-API Management includes several transformation policies that you can use to modify request or response payloads, headers, or status codes. As an example, this section shows you how to configure a custom response header using the `set-header` policy.
-
-
-
-### Set the transformation policy
-
-This example shows how to use the form-based policy editor, which helps you configure many policies without having to edit the policy XML statements directly.
-
-1. Select **Swagger Petstore** > **Design** > **All operations**.
-1. In the **Outbound processing** section, select **+ Add policy**.
-
-   :::image type="content" source="media/transform-api/outbound-policy-small.png" alt-text="Screenshot of navigating to outbound policy in the portal." lightbox="media/transform-api/outbound-policy.png":::
-
-1. In the **Add outbound policy** window, select **Set headers**.
-
-   :::image type="content" source="media/transform-api/set-http-header.png" alt-text="Screenshot of configuring the Set headers policy in the portal.":::
-
-1. To configure the Set headers policy, do the following:
-    1. Under **Name**, enter **Custom header**.
-    1. Under **Value**, select **+ Add value**. Enter *My custom value*.
-    1. Select **Save**.
-  
-1. After configuration, a **set-header** policy element appears in the **Outbound processing** section.
-
-   :::image type="content" source="media/transform-api/set-policy.png" alt-text="Screenshot of the Set headers outbound policies in the portal.":::
-
-
-
 ## Test the transformations
 
 At this point, if you look at the code in the code editor, your policies look like the following code:
 
-   ```
+   ```xml
    <policies>
-      <inbound>
-        <rate-limit-by-key calls="3" renewal-period="15" counter-key="@(context.Subscription.Id)" />
-        <base />
-      </inbound>
-      <backend>
-        <base />
-      </backend>
-      <outbound>
-        <set-header name="X-Powered-By" exists-action="delete" />
-        <set-header name="X-AspNet-Version" exists-action="delete" />
-        <redirect-content-urls />
-        <base />
-      </outbound>
-      <on-error>
-        <base />
-      </on-error>
-   </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.
 
-### Test the stripped response headers
-
-1. Select **Demo Conference API** > **Test**.
-1. Select the **GetSpeakers** operation and select **Send**.
-
-    As you can see, the **X-AspNet-Version** and **X-Powered-By** headers were removed:
+### Test the custom response header
 
-    :::image type="content" source="media/transform-api/stripped-response-headers.png" alt-text="Screenshot showing stripped response headers in the portal.":::
+1. Select **Swagger Petstore** > **Test**.
+1. SSelect the **GET Finds pets by status** operation, and optionally select a different value of the *status* **Query parameter**. Select **Send**.
 
-### Test the replaced URL
+    As you can see, the custom response header is added:
 
-1. Select **Demo Conference API** > **Test**.
-1. Select the **GetSpeakers** operation and select **Send**.
+    :::image type="content" source="media/transform-api/custom-response-header.png" alt-text="Screenshot showing custom response header in the portal.":::
 
-    As you can see, the URLs are replaced.
-
-    :::image type="content" source="media/transform-api/test-replaced-url.png" alt-text="Screenshot showing replaced URLs in the portal.":::
 
 ### Test the rate limit (throttling)
 
-1. Select **Demo Conference API** > **Test**.
-1. Select the **GetSpeakers** operation. Select **Send** four times in a row.
+1. Select **Swagger Petstore** > **Test**.
+1. Select the **GET Finds Pets by Status** operation. Select **Send** several times in a row.
 
-    After sending the request four times, you get the **429 Too Many Requests** response.
+    After sending too many requests in the configured period, you get the **429 Too Many Requests** response.
 
     :::image type="content" source="media/transform-api/test-throttling-new.png" alt-text="Screenshot showing Too Many Requests in the response in the portal.":::
 
@@ -176,9 +159,8 @@ In this tutorial, you learned how to:
 
 > [!div class="checklist"]
 >
-> * Transform an API to strip response headers
-> * Replace original URLs in the body of the API response with API Management gateway URLs
-> * Protect an API by adding rate limit policy (throttling)
+> * Transform an API to set a custom response header
+> * Protect an API by adding a rate limit policy (throttling)
 > * Test the transformations
 
 ## Next steps