wip

gitName · gitName · commit 98aba6d91593 · 2025-01-09T16:13:50.000-08:00
diff --git a/articles/api-management/api-management-get-started-publish-versions.md b/articles/api-management/api-management-get-started-publish-versions.md
@@ -17,6 +17,8 @@ There are times when it's impractical to have all callers to your API use exactl
 
 For background, see [Versions](api-management-versions.md) & [Revisions](api-management-revisions.md).
 
+[!INCLUDE [api-management-workspace-try-it](../../includes/api-management-workspace-try-it.md)]
+
 In this tutorial, you learn how to:
 
 > [!div class="checklist"]
diff --git a/articles/api-management/api-management-get-started-revise-api.md b/articles/api-management/api-management-get-started-revise-api.md
@@ -22,6 +22,8 @@ In Azure API Management, use *revisions* to make nonbreaking API changes so you
 
 For background, see [Versions](api-management-versions.md) and [Revisions](api-management-revisions.md).
 
+[!INCLUDE [api-management-workspace-try-it](../../includes/api-management-workspace-try-it.md)]
+
 In this tutorial, you learn how to:
 
 > [!div class="checklist"]
diff --git a/articles/api-management/api-management-howto-add-products.md b/articles/api-management/api-management-howto-add-products.md
@@ -16,6 +16,8 @@ zone_pivot_groups: api-management-howto-add-products
 
 In Azure API Management, a [*product*](api-management-terminology.md#term-definitions) contains one or more APIs, a usage quota, and the terms of use. After a product is published, developers can [subscribe](api-management-subscriptions.md) to the product and begin to use the product's APIs.  
 
+[!INCLUDE [api-management-workspace-try-it](../../includes/api-management-workspace-try-it.md)]
+
 :::zone pivot="interactive"
 
 In this tutorial, you learn how to:
diff --git a/articles/api-management/api-management-howto-api-inspector.md b/articles/api-management/api-management-howto-api-inspector.md
@@ -16,6 +16,8 @@ ms.custom: devdivchpfy22
 
 This tutorial describes how to inspect (trace) request processing in Azure API Management. Tracing helps you debug and troubleshoot your API.
 
+[!INCLUDE [api-management-workspace-try-it](../../includes/api-management-workspace-try-it.md)]
+
 In this tutorial, you learn how to:
 
 > [!div class="checklist"]
diff --git a/articles/api-management/api-management-key-concepts-experiment.md b/articles/api-management/api-management-key-concepts-experiment.md
@@ -28,7 +28,7 @@ This article provides an overview of common scenarios and key components of Azur
 
 APIs enable digital experiences, simplify application integration, underpin new digital products, and make data and services reusable and universally accessible. ​With the proliferation and increasing dependency on APIs, organizations need to manage them as first-class assets throughout their lifecycle.​
 
-:::image type="content" source="media/api-management-key-concepts-experiment/apis-connected-experiences.png" alt-text="Diagram showing role of APIs in connected experiences.":::
+:::image type="content" source="media/api-management-key-concepts/apis-connected-experiences.png" alt-text="Diagram showing role of APIs in connected experiences.":::
 
 
 Azure API Management helps customers meet these challenges:
@@ -49,7 +49,7 @@ Common scenarios include:
 
 Azure API Management is made up of an API *gateway*, a *management plane*, and a *developer portal*. These components are Azure-hosted and fully managed by default. API Management is available in various [tiers](api-management-features.md) differing in capacity and features.
 
-:::image type="content" source="media/api-management-key-concepts-experiment/api-management-components.png" alt-text="Diagram showing key components of Azure API Management.":::
+:::image type="content" source="media/api-management-key-concepts/api-management-components.png" alt-text="Diagram showing key components of Azure API Management.":::
 
 ## API gateway
 
@@ -89,7 +89,7 @@ Use the management plane to:
 
 The open-source [developer portal][Developer portal] is an automatically generated, fully customizable website with the documentation of your APIs. 
 
-:::image type="content" source="media/api-management-key-concepts-experiment/cover.png" alt-text="Screenshot of API Management developer portal - administrator mode." border="false":::
+:::image type="content" source="media/api-management-key-concepts/cover.png" alt-text="Screenshot of API Management developer portal - administrator mode." border="false":::
 
 API providers can customize the look and feel of the developer portal by adding custom content, customizing styles, and adding their branding. Extend the developer portal further by [self-hosting](developer-portal-self-host.md).
 
diff --git a/articles/api-management/api-management-key-concepts.md b/articles/api-management/api-management-key-concepts.md
diff --git a/articles/api-management/media/api-management-key-concepts/api-management-components.png b/articles/api-management/media/api-management-key-concepts/api-management-components.png
diff --git a/articles/api-management/media/api-management-key-concepts/apis-connected-experiences.png b/articles/api-management/media/api-management-key-concepts/apis-connected-experiences.png
diff --git a/articles/api-management/media/api-management-key-concepts/cover.png b/articles/api-management/media/api-management-key-concepts/cover.png
diff --git a/articles/api-management/mock-api-responses.md b/articles/api-management/mock-api-responses.md
@@ -22,6 +22,8 @@ Backend APIs are imported into an API Management (APIM) API or created and manag
 
 This method lets developers continue with the implementation and testing of the API Management instance even if the backend isn't available to send real responses.
 
+[!INCLUDE [api-management-workspace-try-it](../../includes/api-management-workspace-try-it.md)]
+
 The ability to mock up responses is useful in many scenarios:
 
 + When the API façade is designed first and the backend implementation comes later. Or, the backend is being developed in parallel.
diff --git a/articles/api-management/transform-api.md b/articles/api-management/transform-api.md
@@ -14,7 +14,9 @@ ms.author: danlep
 
 [!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. Policies are a collection of statements that are run sequentially on the request or response of an API that modify the API's behavior. 
+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.
+
+[!INCLUDE [api-management-workspace-try-it](../../includes/api-management-workspace-try-it.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 a simple introduction to API Management policies. For more policy options, see [API Management policies](api-management-policies.md).
 
diff --git a/articles/api-management/visual-studio-code-tutorial.md b/articles/api-management/visual-studio-code-tutorial.md
@@ -15,6 +15,8 @@ ms.custom: devdivchpfy22
 
 In this tutorial, you learn how to use the API Management extension for Visual Studio Code for common operations in API Management. Use the familiar Visual Studio Code environment to import, update, test, and manage APIs.
 
+[!INCLUDE [api-management-workspace-availability](../../includes/api-management-workspace-availability.md)]
+
 You learn how to:
 
 > [!div class="checklist"]
@@ -109,7 +111,7 @@ You need a subscription key for your API Management instance to test the importe
 ### Test an API operation
 
 1. In the Explorer pane, expand the **Operations** node under the *petstore* API that you imported.
-1. Select an operation such as *[GET] Find pet by ID*, and then right-click the operation and select **Test Operation**.
+1. Select an operation such as *[GET] Finds pet by statis*, and then right-click the operation and select **Test Operation**.
 1. In the editor window, substitute `5` for the `petId` parameter in the request URL.
 1. In the editor window, next to **Ocp-Apim-Subscription-Key**, replace `{{SubscriptionKey}}` with the subscription key that you copied.
 1. Select **Send request**.
diff --git a/articles/api-management/workspaces-overview.md b/articles/api-management/workspaces-overview.md
@@ -12,39 +12,37 @@ ms.author: danlep
 
 ---
 
-# What are workspaces in Azure API Management?
+# Federated API management with workspaces
 
 [!INCLUDE [api-management-availability-premium](../../includes/api-management-availability-premium.md)]
 
+Today, organizations are increasingly facing challenges in managing a proliferation of APIs. As the number of APIs and API development teams grows, so does the complexity of managing them. This complexity can lead to increased operational overhead, security risks, and reduced agility. On the one hand, organizations want to establish a centralized API infrastructure to ensure API governance, security, and compliance. On the other hand, they want their API teams to innovate and respond quickly to business needs, without the overhead of managing an API platform.
+
 In API Management, *workspaces* bring a new level of autonomy to an organization's API teams, enabling them to create, manage, and publish APIs faster, more reliably, securely, and productively within an API Management service. By providing isolated administrative access and API runtime, workspaces empower API teams while allowing the API platform team to retain oversight. This includes central monitoring, enforcement of API policies and compliance, and publishing APIs for discovery through a unified developer portal. 
 
 Workspaces function like "folders" within an API Management service:
 
 * Each workspace contains APIs, products, subscriptions, named values, and related resources. 
 * Access to resources within a workspace is managed through Azure's role-based access control (RBAC) with built-in or custom roles assignable to Microsoft Entra accounts. 
-* Each workspace is associated with a *workspace gateway* for routing API traffic to the backend services of APIs in the workspace.
+* Each workspace is associated with one or more *workspace gateways* for routing API traffic to the backend services of APIs in the workspace.
 
 :::image type="content" source="media/workspaces-overview/workspace-concept.png" alt-text="Conceptual diagram of API Management service with workspaces.":::
 
 [!INCLUDE [api-management-workspace-intro-note](../../includes/api-management-workspace-intro-note.md)]
 
-## Federated API management with workspaces
+## Centralized API platform and decentralized API teams
 
-Workspaces add first-class support for a *federated model* of managing APIs in API Management, in addition to already supported centralized and siloed models. See the following table for a comparison of these models.
+Workspaces add first-class support for a *federated model* of managing APIs in your organization, in addition to already supported centralized and siloed models. See the following table for a comparison of these models.
 
-|Model|Description  |
-|---------|---------|
-|**Centralized**<br/><br/>:::image type="content" source="media/workspaces-overview/centralized.png" alt-text="Diagram of the centralized model of Azure API Management." border="false" lightbox="media/workspaces-overview/centralized.png":::      |**Pros**<br/>• Centralized API governance and observability<br/>• Unified developer portal for effective API discovery and onboarding<br/>• Cost-efficiency of the infrastructure<br/><br/>**Cons**<br/>• No segregation of administrative permissions between teams<br/>• API gateway is a single point of failure<br/>• Inability to attribute runtime issues to specific teams<br/>• Burden on platform team to facilitate collaboration may reduce API growth     |
-|**Siloed**<br/><br/>:::image type="content" source="media/workspaces-overview/siloed.png"  alt-text="Diagram of the siloed model of Azure API Management." border="false" lightbox="media/workspaces-overview/siloed.png":::       |**Pros**<br/>• Segregation of administrative permissions between teams increases productivity and security<br/>• Segregation of API runtime between teams increases API reliability, resiliency, and security<br/>• Runtime issues are contained and attributable to specific teams<br/><br/>**Cons**<br/>• Lack of centralized API governance and observability<br/>• Lack of unified developer portal<br/>• Increased cost and harder platform management​    | 
-|**Federated**<br/><br/>:::image type="content" source="media/workspaces-overview/federated.png" alt-text="Diagram of the federated model of Azure API Management." border="false" lightbox="media/workspaces-overview/federated.png":::       |**Pros**<br/>• Centralized API governance and observability<br/>• Unified developer portal for effective API discovery and onboarding<br/>• Segregation of administrative permissions between teams increases productivity and security<br/>• Segregation of API runtime between teams increases API reliability, resiliency, and security<br/>• Runtime issues are contained and attributable to specific teams<br/><br/>**Cons**<br/>• Platform cost and management difficulty greater than in the centralized model but lower than in the siloed model |
+[!INCLUDE [api-management-platform-deployment-models](../../includes/api-management-platform-deployment-models.md)]
 
 ## Example scenario overview
 
 An organization that manages APIs using Azure API Management may have multiple development teams that develop, define, maintain, and productize different sets of APIs. Workspaces allow these teams to use API Management to manage, access, and secure their APIs separately, and independently of managing the service infrastructure.
 
 The following is a sample workflow for creating and using a workspace.
 
-1. A central API platform team that manages the API Management instance creates a workspace and assigns permissions to workspace collaborators using RBAC roles - for example, permissions to create or read resources in the workspace. A dedicated API gateway is also created for the workspace.
+1. A central API platform team that manages the API Management instance creates a workspace and assigns permissions to workspace collaborators using RBAC roles - for example, permissions to create or read resources in the workspace. A workspace-scoped API gateway is also created for the workspace.
 
 1. A central API platform team uses DevOps tools to create a DevOps pipeline for APIs in that workspace. 
 
diff --git a/includes/api-management-platform-deployment-models.md b/includes/api-management-platform-deployment-models.md
@@ -8,6 +8,6 @@ ms.author: danlep
 
 |Model|Description  |
 |---------|---------|
-|**Centralized**<br/><br/>:::image type="content" source="media/api-management-platform-deployment-models/centralized.png" alt-text="Diagram of the centralized model of Azure API Management." border="false" lightbox="media/api-management-platform-deployment-models/centralized.png":::      |**Pros**<br/>• Centralized API governance and observability<br/>• Unified developer portal for effective API discovery and onboarding<br/>• Cost-efficiency of the infrastructure<br/><br/>**Cons**<br/>• No segregation of administrative permissions between teams<br/>• API gateway is a single point of failure<br/>• Inability to attribute runtime issues to specific teams<br/>• Burden on platform team to facilitate collaboration may reduce API growth     |
-|**Siloed**<br/><br/>:::image type="content" source="media/api-management-platform-deployment-models/siloed.png"  alt-text="Diagram of the siloed model of Azure API Management." border="false" lightbox="media/api-management-platform-deployment-models/siloed.png":::       |**Pros**<br/>• Segregation of administrative permissions between teams increases productivity and security<br/>• Segregation of API runtime between teams increases API reliability, resiliency, and security<br/>• Runtime issues are contained and attributable to specific teams<br/><br/>**Cons**<br/>• Lack of centralized API governance and observability<br/>• Lack of unified developer portal<br/>• Increased cost and harder platform management​    | 
-|**Federated**<br/><br/>:::image type="content" source="media/api-management-platform-deployment-models/federated.png" alt-text="Diagram of the federated model of Azure API Management." border="false" lightbox="media/api-management-platform-deployment-models/federated.png":::       |**Pros**<br/>• Centralized API governance and observability<br/>• Unified developer portal for effective API discovery and onboarding<br/>• Segregation of administrative permissions between teams increases productivity and security<br/>• Segregation of API runtime between teams increases API reliability, resiliency, and security<br/>• Runtime issues are contained and attributable to specific teams<br/><br/>**Cons**<br/>• Platform cost and management difficulty greater than in the centralized model but lower than in the siloed model |
+|**Centralized**<br/><br/>:::image type="content" source="media/workspaces-overview/centralized.png" alt-text="Diagram of the centralized model of Azure API Management." border="false" lightbox="media/workspaces-overview/centralized.png":::      |**Pros**<br/>• Centralized API governance and observability<br/>• Unified developer portal for effective API discovery and onboarding<br/>• Cost-efficiency of the infrastructure<br/><br/>**Cons**<br/>• No segregation of administrative permissions between teams<br/>• API gateway is a single point of failure<br/>• Inability to attribute runtime issues to specific teams<br/>• Burden on platform team to facilitate collaboration may reduce API growth     |
+|**Siloed**<br/><br/>:::image type="content" source="media/workspaces-overview/siloed.png"  alt-text="Diagram of the siloed model of Azure API Management." border="false" lightbox="media/workspaces-overview/siloed.png":::       |**Pros**<br/>• Segregation of administrative permissions between teams increases productivity and security<br/>• Segregation of API runtime between teams increases API reliability, resiliency, and security<br/>• Runtime issues are contained and attributable to specific teams<br/><br/>**Cons**<br/>• Lack of centralized API governance and observability<br/>• Lack of unified developer portal<br/>• Increased cost and harder platform management​    | 
+|**Federated**<br/><br/>:::image type="content" source="media/workspaces-overview/federated.png" alt-text="Diagram of the federated model of Azure API Management." border="false" lightbox="media/workspaces-overview/federated.png":::       |**Pros**<br/>• Centralized API governance and observability<br/>• Unified developer portal for effective API discovery and onboarding<br/>• Segregation of administrative permissions between teams increases productivity and security<br/>• Segregation of API runtime between teams increases API reliability, resiliency, and security<br/>• Runtime issues are contained and attributable to specific teams<br/><br/>**Cons**<br/>• Platform cost and management difficulty greater than in the centralized model but lower than in the siloed model |
diff --git a/includes/api-management-workspace-try-it.md b/includes/api-management-workspace-try-it.md
@@ -0,0 +1,9 @@
+---
+author: dlepow
+ms.service: azure-api-management
+ms.topic: include
+ms.date: 01/09/2025
+ms.author: danlep
+---
+> [!TIP]
+> You can also use this feature in [workspaces](../articles/api-management/workspaces-overview.md).
