Merge pull request #283778 from dlepow/postm

[APIM] Postman references

Author: v-dirichards

articles/api-management/TOC.yml

@@ -423,11 +423,12 @@
       href: api-management-howto-configure-notifications.md
   - name: Export APIs
     items:
-    - name: Test and monitor APIs in Postman
-      displayName: collection
-      href: export-api-postman.md
+
     - name: Inventory APIs in API Center
       href: ../api-center/import-api-management-apis.md?toc=%2Fazure%2Fapi-management%2Ftoc.json&bc=/azure/api-management/breadcrumb/toc.json
+    - name: Export APIs to Postman for API development
+      displayName: collection
+      href: export-api-postman.md
     - name: Export APIs to the Power Platform
       items:
         - name: Export API as custom connector
@@ -659,14 +660,14 @@
       href: breaking-changes/metrics-retirement-aug-2023.md
     - name: Virtual network changes (September 2023)
       href: breaking-changes/rp-source-ip-address-change-sep-2023.md
-    - name: API version retirements (June 2024)
-      href: breaking-changes/api-version-retirement-sep-2023.md
     - name: Self-hosted gateway v0/v1 retirements (October 2023)
       href: breaking-changes/self-hosted-gateway-v0-v1-retirement-oct-2023.md
     - name: Deprecated (legacy) developer portal (October 2023)
       href: breaking-changes/legacy-portal-retirement-oct-2023.md
     - name: Workspaces preview breaking changes (June 2024)
       href: breaking-changes/workspaces-breaking-changes-june-2024.md
+    - name: API version retirements (June 2024)
+      href: breaking-changes/api-version-retirement-sep-2023.md
     - name: stv1 compute platform retirement (August 2024)
       href: breaking-changes/stv1-platform-retirement-august-2024.md
     - name: Workspaces preview breaking changes, part 2 (March 2025)

articles/api-management/api-management-sample-send-request.md

@@ -3,11 +3,9 @@ title: Using API Management service to generate HTTP requests
 description: Learn to use request and response policies in API Management to call external services from your API
 services: api-management
 author: dlepow
-manager: erikre
-ms.assetid: 4539c0fa-21ef-4b1c-a1d4-d89a38c242fa
 ms.service: azure-api-management
 ms.topic: article
-ms.date: 04/14/2022
+ms.date: 08/05/2024
 ms.author: danlep
 
 ---
@@ -17,7 +15,7 @@ ms.author: danlep
 
 The policies available in Azure API Management service can do a wide range of useful work based purely on the incoming request, the outgoing response, and basic configuration information. However, being able to interact with external services from API Management policies opens up many more opportunities.
 
-You have previously seen how to interact with the [Azure Event Hub service for logging, monitoring, and analytics](api-management-log-to-eventhub-sample.md). This article demonstrates policies that allow you to interact with any external HTTP-based service. These policies can be used for triggering remote events or for retrieving information that is used to manipulate the original request and response in some way.
+You have previously seen how to interact with the [Azure Event Hubs service for logging, monitoring, and analytics](api-management-log-to-eventhub-sample.md). This article demonstrates policies that allow you to interact with any external HTTP-based service. These policies can be used for triggering remote events or for retrieving information that is used to manipulate the original request and response in some way.
 
 ## Send-One-Way-Request
 Possibly the simplest external interaction is the fire-and-forget style of request that allows an external service to be notified of some kind of important event. The control flow policy `choose` can be used to detect any kind of condition that you are interested in.  If the condition is satisfied, you can make an external HTTP request using the [send-one-way-request](./send-one-way-request-policy.md) policy. This could be a request to a messaging system like Hipchat or Slack, or a mail API like SendGrid or MailChimp, or for critical support incidents something like PagerDuty. All of these messaging systems have simple HTTP APIs that can be invoked.
@@ -95,7 +93,7 @@ The `response-variable-name` attribute is used to give access the returned respo
 
 From the response object, you can retrieve the body and RFC 7622 tells API Management that the response must be a JSON object and must contain at least a property called `active` that is a boolean value. When `active` is true then the token is considered valid.
 
-Alternatively, if the authorization server doesn't include the "active" field to indicate whether the token is valid, use a tool like Postman to determine what properties are set in a valid token. For example, if a valid token response contains a property called "expires_in", check whether this property name exists in the authorization server response this way:
+Alternatively, if the authorization server doesn't include the "active" field to indicate whether the token is valid, use an HTTP client tool such as `curl` to determine what properties are set in a valid token. For example, if a valid token response contains a property called "expires_in", check whether this property name exists in the authorization server response this way:
 
 ```xml
 <when condition="@(((IResponse)context.Variables["tokenstate"]).Body.As<JObject>().Property("expires_in") == null)">

articles/api-management/devops-api-development-templates.md

@@ -43,7 +43,7 @@ Both GitHub and Azure Repos allow approval pipelines to be configured that run w
 * API specification linters such as [Spectral][12] to ensure that the definition meets API standards required by the organization.  
 * Breaking change detection using tools such as [openapi-diff][13].
 * Security audit and assessment tools.  [OWASP maintains a list of tools][14] for security scanning.
-* Automated API test frameworks such as [Newman][15], a test runner for [Postman collections][16].
+* Automated API test frameworks.
 
 > [!NOTE]
 > Azure APIs must conform to a [strict set of guidelines][26] that you can use as a starting point for your own API guidelines.  There is a [Spectral configuration][27] for enforcing the guidelines.
@@ -88,7 +88,6 @@ Review [Automated API deployments with APIOps][28] in the Azure Architecture Cen
 * [Azure APIOps Toolkit][5] provides a workflow for API Management DevOps.
 * [Spectral][12] provides a linter for OpenAPI specifications.
 * [openapi-diff][13] provides a breaking change detector for OpenAPI v3 definitions.
-* [Newman][15] provides an automated test runner for Postman collections.
 
 <!-- Links -->
 [1]: https://www.w3.org/TR/wsdl20/

articles/api-management/export-api-postman.md

@@ -1,19 +1,22 @@
 ---
 title: Export API from Azure API Management to Postman for testing and monitoring | Microsoft Docs
-description: Learn how to export an API definition from API Management to Postman and use Postman for API testing and monitoring
+description: Learn how to export an API definition from API Management to Postman and use Postman for API testing, monitoring, and development
 author: dlepow
 
 ms.service: azure-api-management
 ms.topic: how-to
-ms.date: 10/11/2022
+ms.date: 08/06/2024
 ms.author: danlep
 ---
-# Export API definition to Postman for API testing and monitoring
+# Export API definition to Postman for API testing, monitoring, and development
 
 [!INCLUDE [api-management-availability-all-tiers](../../includes/api-management-availability-all-tiers.md)]
 
 To enhance development of your APIs, you can export an API fronted in API Management to [Postman](https://www.postman.com/product/what-is-postman/). Export an API definition from API Management as a Postman [collection](https://learning.postman.com/docs/getting-started/creating-the-first-collection/) so that you can use Postman's tools to design, document, test, monitor, and collaborate on APIs. 
 
+> [!NOTE]
+> Only the API definition can be exported directly from API Management to Postman. Other information such as policies or subscription keys isn't exported.
+
 ## Prerequisites
 
 + Complete the following quickstart: [Create an Azure API Management instance](get-started-create-service-instance.md).
@@ -22,8 +25,6 @@ To enhance development of your APIs, you can export an API fronted in API Manage
     > [!NOTE]
     > Currently, you can only export HTTP APIs from API Management directly to Postman.
     
-    For testing authorization in Postman as outlined later in this article, the API should require a subscription.
-
 + A [Postman](https://www.postman.com) account, which you can use to access Postman for Web.
     * Optionally, [download and install](https://learning.postman.com/docs/getting-started/installation-and-updates/) the Postman desktop app locally.
 
@@ -45,30 +46,18 @@ To enhance development of your APIs, you can export an API fronted in API Manage
 
     :::image type="content" source="media/export-api-postman/postman-collection-documentation.png" alt-text="Screenshot of collection imported to Postman."::: 
 
-## Authorize requests in Postman  
+## API development with API Management and Postman  
 
-If the API you exported requires a subscription, you'll need to configure a valid subscription key from your API Management instance to send requests from Postman. 
+API developers can rapidly iterate on API changes by using Postman's API testing, monitoring, and development capabilities.
 
-Use the following steps to configure a subscription key as a secret variable for the collection.
+APIs developed in Postman can then be exported and imported back into API Management as API revisions. This enables you to develop APIs in Postman and then deploy them to API Management for runtime access and management. [Learn more](https://learning.postman.com/docs/designing-and-developing-your-api/deploying-an-api/deploying-an-api-azure/)
 
-1. In your Postman workspace, select **Environments** > **Create environment**.
-1. Enter a name for the environment such as *Azure API Management*.
-1. Add a variable with the following values:
-    1. Name -  *apiKey*
-    1. Type - **secret**
-    1. Initial value - a valid API Management subscription key for the API
-1. Select **Save**.
-1. Select **Collections** and the name of the collection that you imported.
-1. Select the **Authorization** tab.
-1. In the upper right, select the name of the environment you created, such as *Azure API Management*.
-1. For the key **Ocp-Apim-Subscription-Key**, enter the variable name `{{apiKey}}`. Select **Save**.
 
-    :::image type="content" source="media/export-api-postman/postman-api-authorization.png" alt-text="Screenshot of configuring secret API key in Postman.":::
-1. Test your configuration by selecting an operation in your API such as a `GET` operation, and select **Send**.
-    
-    If correctly configured, the operation returns a `200 OK` status and some output.
+> [!CAUTION]
+> Use care when passing API Management subscription keys or other sensitive data in Postman. [Postman Vault](https://learning.postman.com/docs/sending-requests/postman-vault/postman-vault-secrets/) is recommended to store sensitive data as vault secrets in your instance of Postman, so you can safely reuse secrets in your collections and requests.
 
-## Next steps
+## Related content
 
-* Learn more about [importing APIs to Postman](https://learning.postman.com/docs/designing-and-developing-your-api/importing-an-api/).
+* [Blog: Enhanced API developer experience with the Microsoft-Postman partnership](https://techcommunity.microsoft.com/t5/apps-on-azure-blog/enhanced-api-developer-experience-with-the-microsoft-postman/ba-p/3650304)
+* Learn more about [importing API definitions to Postman](https://learning.postman.com/docs/designing-and-developing-your-api/importing-an-api/).
 * Learn more about [authorizing requests in Postman](https://learning.postman.com/docs/sending-requests/authorization/).

articles/api-management/front-door-api-management.md

@@ -1,12 +1,13 @@
 ---
 title: Configure Azure Front Door in front of Azure API Management
-description: Learn how to front your API Management instance with Azure Front Door Standard/Premium to provide global HTTPS load balancing, TLS offloading, dynamic request acceleration, and other capabilities.
+description: Learn how to front your API Management instance with Azure Front Door for global HTTPS load balancing, TLS offloading, dynamic request acceleration, and more.
 services: api-management
 author: dlepow
 
+
 ms.service: azure-api-management
 ms.topic: how-to
-ms.date: 09/27/2022
+ms.date: 08/06/2024
 ms.author: danlep
 ---
 # Configure Front Door Standard/Premium in front of Azure API Management
@@ -78,19 +79,17 @@ We recommend updating the default route that's associated with the API Managemen
 
 ### Test the configuration
 
-Test the Front Door profile configuration by calling an API hosted by API Management. First, call the API directly through the API Management gateway to ensure that the API is reachable. Then, call the API through Front Door. To test, you can use a command line client such as `curl` for the calls, or a tool such as [Postman](https://www.getpostman.com).
+Test the Front Door profile configuration by calling an API hosted by API Management, for example, the Demo Conference API. First, call the API directly through the API Management gateway to ensure that the API is reachable. Then, call the API through Front Door.
 
 ### Call an API directly through API Management
 
-In the following example, an operation in the Demo Conference API hosted by the API Management instance is called directly using Postman. In this example, the instance's hostname is in the default `azure-api.net` domain, and a valid subscription key is passed using a request header. A successful response shows `200 OK` and returns the expected data:
+To call an API directly through the API Management gateway, you can use a command line client such as `curl` or another HTTP client. A successful response returns a `200 OK` HTTP response and the expected data:
 
-:::image type="content" source="media/front-door-api-management/test-api-management-gateway.png" alt-text="Screenshot showing calling API Management endpoint directly using Postman.":::
+:::image type="content" source="media/front-door-api-management/test-api-management-gateway.png" alt-text="Screenshot showing calling API Management endpoint directly using an HTTP client.":::
 
 ### Call an API directly through Front Door
 
-In the following example, the same operation in the Demo Conference API is called using the Front Door endpoint configured for your instance. The endpoint's hostname in the `azurefd.net` domain is shown in the portal on the **Overview** page of your Front Door profile. A successful response shows `200 OK` and returns the same data as in the previous example:
-
-:::image type="content" source="media/front-door-api-management/test-front-door-gateway.png" alt-text="Screenshot showing calling Front Door endpoint using Postman.":::
+Call the same API operation using the Front Door endpoint configured for your instance. The endpoint's hostname in the `azurefd.net` domain is shown in the portal on the **Overview** page of your Front Door profile. A successful response shows `200 OK` and returns the same data as in the previous example.
 
 ## Restrict incoming traffic to API Management instance