review comments

gitName · gitName · commit e46e500b7a3a · 2025-01-28T10:09:35.000-08:00
diff --git a/articles/api-management/api-management-key-concepts.md b/articles/api-management/api-management-key-concepts.md
@@ -102,7 +102,7 @@ Using the developer portal, API consumers can:
 
 ## Federated API platform deployment with workspaces
 
-Azure API Management supports several deployment models for managing an organization's API portfolio, including *centralized*, *siloed*, and *federated*. The models offer different degrees of centralized control over the API platform infrastructure, API governance, and API discovery. For organizations that want to manage API complexity by empowering decentralized teams to develop and manage their own APIs, API Management supports a federated model with workspaces.
+Azure API Management supports several deployment models for managing an organization's API portfolio, including *centralized*, *siloed*, and *federated*. The models offer different degrees of centralized control over the API platform infrastructure, API governance, and API discovery. For organizations that want to manage API complexity by empowering decentralized teams to develop and manage their own APIs, API Management offers first-class support for a federated model with *workspaces*.
 
 [!INCLUDE [workspaces-benefits](../../includes/workspaces-benefits.md)]
 
diff --git a/articles/api-management/workspaces-overview.md b/articles/api-management/workspaces-overview.md
@@ -6,7 +6,7 @@ author: dlepow
  
 ms.service: azure-api-management
 ms.topic: concept-article
-ms.date: 07/19/2024
+ms.date: 01/27/2025
 ms.author: danlep
 #customer intent: As administrator of an API Management instance, I want to learn about using workspaces to manage APIs in a decentralized way, so that I can enable my development teams to manage and productize their own APIs.
 
@@ -16,20 +16,15 @@ ms.author: danlep
 
 [!INCLUDE [api-management-availability-premium](../../includes/api-management-availability-premium.md)]
 
-Today, organizations increasingly face 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.
+This article provides an overview of API Management *workspaces* and how they empower decentralized API development teams to manage and productize their APIs in a common service infrastructure. 
 
-[!INCLUDE [workspaces-benefits](../../includes/workspaces-benefits.md)]
-Workspaces function like "folders" within an API Management service:
+## Why do organizations need workspaces?
 
-* 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 one or more *workspace gateways* for routing API traffic to the backend services of APIs in the workspace.
+Today, organizations increasingly face 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.
 
-:::image type="content" source="media/workspaces-overview/workspace-concept.png" alt-text="Conceptual diagram of API Management service with workspaces.":::
+## Workspaces support centralized API platform and decentralized API teams
 
-[!INCLUDE [api-management-workspace-intro-note](../../includes/api-management-workspace-intro-note.md)]
-
-## Centralized API platform and decentralized API teams
+[!INCLUDE [workspaces-benefits](../../includes/workspaces-benefits.md)]
 
 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.
 
@@ -39,6 +34,20 @@ Workspaces add first-class support for a *federated model* of managing APIs in y
 |**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 |
 
+## How do workspaces work?
+
+Workspaces function like "folders" within an API Management service:
+
+* Each workspace contains APIs, products, subscriptions, named values, and related resources. See the API Management [REST API reference](/rest/api/apimanagement/workspace?view=rest-apimanagement-2023-09-01-preview&preserve-view=true) for a full list of resources and operations supported in workspaces.
+* Teams' 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 one or more [workspace gateways](#workspace-gateway) 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)]
+
+While workspaces are managed independently from the API Management service and other workspaces, by design they can reference selected service-level resources. See [Workspaces and other API Management features](#workspaces-and-other-api-management-features), later in this article.
+
 ## 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.
@@ -53,15 +62,9 @@ The following is a sample workflow for creating and using a workspace.
 
 1. The central API platform team manages the infrastructure of the service, such as monitoring, resiliency, and enforcement of all-APIs policies. 
 
-## API management in a workspace
-
-Teams manage their own APIs, products, subscriptions, backends, policies, loggers, and other resources within workspaces. See the API Management [REST API reference](/rest/api/apimanagement/workspace?view=rest-apimanagement-2023-09-01-preview&preserve-view=true) for a full list of resources and operations supported in workspaces. 
-
-While workspaces are managed independently from the API Management service and other workspaces, by design they can reference selected service-level resources. See [Workspaces and other API Management features](#workspaces-and-other-api-management-features), later in this article.
-
 ## Workspace gateway
 
-Each workspace can be associated with workspace gateways to enable runtime of APIs managed within the workspace. The workspace gateway is a standalone Azure resource with the same core functionality as the gateway built into your API Management service. 
+Each workspace is associated with one or more workspace gateways to enable runtime of APIs managed within the workspace. The workspace gateway is a standalone Azure resource with the same core functionality as the gateway built into your API Management service. 
 
 Workspace gateways are managed independently from the API Management service and from each other. They ensure isolation of runtime between workspaces, increasing API reliability, resiliency, and security and enabling attribution of runtime issues to workspaces. 
 
@@ -130,7 +133,7 @@ Workspaces are designed to be self-contained to maximize segregation of administ
     For security reasons, it's not possible to reference service-level resources from workspace-level policies (for example, named values) or by resource names, such as `backend-id` in the [set-backend-service](set-backend-service-policy.md) policy. 
 
     > [!IMPORTANT]
-    > All resources in an API Management service (for example, APIs, products, tags, or subscriptions) need to have unique names, even if they are located in different workspaces. There can't be any resources of the same type and with the same Azure resource name in the same workspace, in other workspaces, or on the service level.
+    > All resources in an API Management service (for example, APIs, products, tags, or subscriptions) need to have unique names, even if they're located in different workspaces. There can't be any resources of the same type and with the same Azure resource name in the same workspace, in other workspaces, or on the service level.
     >  
 
 * **Developer portal** - Workspaces are an administrative concept and aren't surfaced as such to developer portal consumers, including through the developer portal UI and the underlying API. APIs and products within a workspace can be published to the developer portal, just like APIs and products on the service level.  
diff --git a/includes/api-management-workspace-try-it.md b/includes/api-management-workspace-try-it.md
@@ -2,8 +2,8 @@
 author: dlepow
 ms.service: azure-api-management
 ms.topic: include
-ms.date: 01/09/2025
+ms.date: 01/27/2025
 ms.author: danlep
 ---
 > [!TIP]
-> You can also use this feature in [workspaces](../articles/api-management/workspaces-overview.md).
+> API teams can use this feature in [workspaces](../articles/api-management/workspaces-overview.md). Workspaces provide isolated administrative access to APIs and their own API runtime environments.
diff --git a/includes/workspaces-benefits.md b/includes/workspaces-benefits.md
@@ -6,5 +6,5 @@ ms.date: 08/08/2023
 ms.author: danlep
 ---
 
-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.
+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.
 
