Merge pull request #33599 from wwlpublish/69aa3fff82c72acb43788a7af071ca25-live

v-ccolin · web-flow · commit 339443bdcccc · 2023-04-25T08:19:47.000+01:00
Modules/M01-implement-azure-api-management
diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json
@@ -21789,6 +21789,11 @@
       "source_path": "learn-pr/wwl-azure/work-with-cosmos-db/7-summary.md",
       "redirect_url": "https://learn.microsoft.com/training/modules/work-with-cosmos-db/8-summary",
       "redirect_document_id": false
+    },
+    {
+      "source_path": "learn-pr/wwl-azure/explore-api-management/8-import-api.md",
+      "redirect_url": "https://learn.microsoft.com/training/modules/explore-api-management/8-exercise-import-api",
+      "redirect_document_id": false
     }
   ]
 }
diff --git a/learn-pr/wwl-azure/explore-api-management/1-introduction.yml b/learn-pr/wwl-azure/explore-api-management/1-introduction.yml
@@ -4,7 +4,7 @@ title: Introduction
 metadata:
   title: Introduction
   description: "Introduction"
-  ms.date: 02/05/2023
+  ms.date: 04/25/2023
   author: wwlpublish
   ms.author: jeffko
   ms.topic: interactive-tutorial
diff --git a/learn-pr/wwl-azure/explore-api-management/10-summary.yml b/learn-pr/wwl-azure/explore-api-management/10-summary.yml
@@ -4,7 +4,7 @@ title: Summary
 metadata:
   title: Summary
   description: "Summary"
-  ms.date: 02/05/2023
+  ms.date: 04/25/2023
   author: wwlpublish
   ms.author: jeffko
   ms.topic: interactive-tutorial
diff --git a/learn-pr/wwl-azure/explore-api-management/2-api-management-overview.yml b/learn-pr/wwl-azure/explore-api-management/2-api-management-overview.yml
@@ -4,7 +4,7 @@ title: Discover the API Management service
 metadata:
   title: Discover the API Management service
   description: "Discover the API Management service"
-  ms.date: 02/05/2023
+  ms.date: 04/25/2023
   author: wwlpublish
   ms.author: jeffko
   ms.topic: interactive-tutorial
diff --git a/learn-pr/wwl-azure/explore-api-management/3-api-gateways.yml b/learn-pr/wwl-azure/explore-api-management/3-api-gateways.yml
@@ -4,7 +4,7 @@ title: Explore API gateways
 metadata:
   title: Explore API gateways
   description: "Explore API gateways"
-  ms.date: 02/05/2023
+  ms.date: 04/25/2023
   author: wwlpublish
   ms.author: jeffko
   ms.topic: interactive-tutorial
diff --git a/learn-pr/wwl-azure/explore-api-management/4-api-management-policies.yml b/learn-pr/wwl-azure/explore-api-management/4-api-management-policies.yml
@@ -4,7 +4,7 @@ title: Explore API Management policies
 metadata:
   title: Explore API Management policies
   description: "Explore API Management policies"
-  ms.date: 02/05/2023
+  ms.date: 04/25/2023
   author: wwlpublish
   ms.author: jeffko
   ms.topic: interactive-tutorial
diff --git a/learn-pr/wwl-azure/explore-api-management/5-create-advanced-policies.yml b/learn-pr/wwl-azure/explore-api-management/5-create-advanced-policies.yml
@@ -4,7 +4,7 @@ title: Create advanced policies
 metadata:
   title: Create advanced policies
   description: "Create advanced policies"
-  ms.date: 02/05/2023
+  ms.date: 04/25/2023
   author: wwlpublish
   ms.author: jeffko
   ms.topic: interactive-tutorial
diff --git a/learn-pr/wwl-azure/explore-api-management/6-secure-access-api-subscriptions.yml b/learn-pr/wwl-azure/explore-api-management/6-secure-access-api-subscriptions.yml
@@ -4,7 +4,7 @@ title: Secure APIs by using subscriptions
 metadata:
   title: Secure APIs by using subscriptions
   description: "Secure APIs by using subscriptions"
-  ms.date: 02/05/2023
+  ms.date: 04/25/2023
   author: wwlpublish
   ms.author: jeffko
   ms.topic: interactive-tutorial
diff --git a/learn-pr/wwl-azure/explore-api-management/7-secure-access-api-certificates.yml b/learn-pr/wwl-azure/explore-api-management/7-secure-access-api-certificates.yml
@@ -4,7 +4,7 @@ title: Secure APIs by using certificates
 metadata:
   title: Secure APIs by using certificates
   description: "Secure APIs by using certificates"
-  ms.date: 02/05/2023
+  ms.date: 04/25/2023
   author: wwlpublish
   ms.author: jeffko
   ms.topic: interactive-tutorial
diff --git a/learn-pr/wwl-azure/explore-api-management/8-exercise-import-api.yml b/learn-pr/wwl-azure/explore-api-management/8-exercise-import-api.yml
@@ -0,0 +1,14 @@
+### YamlMime:ModuleUnit
+uid: learn.wwl.explore-api-management.exercise-create-backend-api
+title: Exercise - Create a backend API
+metadata:
+  title: Exercise - Create a backend API
+  description: "Exercise - Create a backend API"
+  ms.date: 04/25/2023
+  author: wwlpublish
+  ms.author: jeffko
+  ms.topic: interactive-tutorial
+  ms.prod: learning-azure
+durationInMinutes: 15
+content: |
+  [!include[](includes/8-exercise-import-api.md)]
diff --git a/learn-pr/wwl-azure/explore-api-management/8-import-api.yml b/learn-pr/wwl-azure/explore-api-management/8-import-api.yml
diff --git a/learn-pr/wwl-azure/explore-api-management/9-knowledge-check.yml b/learn-pr/wwl-azure/explore-api-management/9-knowledge-check.yml
@@ -4,7 +4,7 @@ title: Knowledge check
 metadata:
   title: Knowledge check
   description: "Knowledge check"
-  ms.date: 02/05/2023
+  ms.date: 04/25/2023
   author: wwlpublish
   ms.author: jeffko
   ms.topic: interactive-tutorial
@@ -17,21 +17,21 @@ quiz:
     choices:
     - content: "API gateway"
       isCorrect: false
-      explanation: "That's incorrect. The API gateway routes calls, performs API transforms, and verifies keys."
+      explanation: "Incorrect. The API gateway routes calls, performs API transforms, and verifies keys."
     - content: "Azure portal"
       isCorrect: false
-      explanation: "That's incorrect. The Azure portal is the administrative interface where you set up your API program."
+      explanation: "Incorrect. The Azure portal is the administrative interface where you set up your API program."
     - content: "Developer portal"
       isCorrect: true
-      explanation: "That's correct. The Developer portal serves as the main web presence for developers, and is where they can subscribe to get API keys."
+      explanation: "Correct. The Developer portal serves as the main web presence for developers, and is where they can subscribe to get API keys."
   - content: "Which of the following API Management policies would one use if one wants to apply a policy based on a condition?"
     choices:
     - content: "forward-request"
       isCorrect: false
-      explanation: "That's incorrect. The forward-request policy forwards the incoming request to the backend service specified in the request context."
+      explanation: "Incorrect. The forward-request policy forwards the incoming request to the backend service specified in the request context."
     - content: "choose"
       isCorrect: true
-      explanation: "That's correct. The choose policy applies enclosed policy statements based on the outcome of evaluation of boolean expressions."
+      explanation: "Correct. The choose policy applies enclosed policy statements based on the outcome of evaluation of boolean expressions."
     - content: "return-response"
       isCorrect: false
-      explanation: "That's incorrect. The return-response policy aborts pipeline execution and returns either a default or custom response to the caller."
+      explanation: "Incorrect. The return-response policy aborts pipeline execution and returns either a default or custom response to the caller."
diff --git a/learn-pr/wwl-azure/explore-api-management/includes/2-api-management-overview.md b/learn-pr/wwl-azure/explore-api-management/includes/2-api-management-overview.md
@@ -1,51 +1,56 @@
 
 API Management provides the core functionality to ensure a successful API program through developer engagement, business insights, analytics, security, and protection. Each API consists of one or more operations, and each API can be added to one or more products. To use an API, developers subscribe to a product that contains that API, and then they can call the API's operation, subject to any usage policies that may be in effect.
 
-The system is made up of the following components:
+## API Management components
+
+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](/azure/api-management/api-management-features) differing in capacity and features.
 
 * The **API gateway** is the endpoint that:
-    * Accepts API calls and routes them to your backend(s).
-    * Verifies API keys, JWT tokens, certificates, and other credentials.
-    * Enforces usage quotas and rate limits.
-    * Transforms your API on the fly without code modifications.
-    * Caches backend responses where set up.
-    * Logs call metadata for analytics purposes.
-
-* The **Azure portal** is the administrative interface where you set up your API program. Use it to:
-    * Define or import API schema.
-    * Package APIs into products.
-    * Set up policies like quotas or transformations on the APIs.
-    * Get insights from analytics.
-    * Manage users.
-
-* The **Developer portal** serves as the main web presence for developers, where they can:
-    * Read API documentation.
-    * Try out an API via the interactive console.
-    * Create an account and subscribe to get API keys.
-    * Access analytics on their own usage.
+    * Accepts API calls and routes them to appropriate backends
+    * Verifies API keys and other credentials presented with requests
+    * Enforces usage quotas and rate limits
+    * Transforms requests and responses specified in policy statements
+    * Caches responses to improve response latency and minimize the load on backend services
+    * Emits logs, metrics, and traces for monitoring, reporting, and troubleshooting
+
+* The **management plane** is the administrative interface where you set up your API program. Use it to:
+    * Provision and configure API Management service settings
+    * Define or import API schema
+    * Package APIs into products
+    * Set up policies like quotas or transformations on the APIs
+    * Get insights from analytics
+    * Manage users
+
+* The **Developer portal** is an automatically generated, fully customizable website with the documentation of your APIs. Using the developer portal, developers can:
+    * Read API documentation
+    * Call an API via the interactive console
+    * Create an account and subscribe to get API keys
+    * Access analytics on their own usage
+    * Download API definitions
+    * Manage API keys
 
 ## Products
 
-Products are how APIs are surfaced to developers. Products in API Management have one or more APIs, and are configured with a title, description, and terms of use. Products can be **Open** or **Protected**. Protected products must be subscribed to before they can be used, while open products can be used without a subscription. Subscription approval is configured at the product level and can either require administrator approval, or be auto-approved.
+Products are how APIs are surfaced to developers. Products in API Management have one or more APIs, and are configured with a title, description, and terms of use. Products can be **Open** or **Protected**. Protected products must be subscribed to before they can be used, while open products can be used without a subscription. Subscription approval is configured at the product level and can either require administrator approval, or be autoapproved.
 
 ## Groups
 
 Groups are used to manage the visibility of products to developers. API Management has the following immutable system groups:
 
-* **Administrators** - Azure subscription administrators are members of this group. Administrators manage API Management service instances, creating the APIs, operations, and products that are used by developers.
-* **Developers** - Authenticated developer portal users fall into this group. Developers are the customers that build applications using your APIs. Developers are granted access to the developer portal and build applications that call the operations of an API.
-* **Guests** - Unauthenticated developer portal users, such as prospective customers visiting the developer portal of an API Management instance fall into this group. They can be granted certain read-only access, such as the ability to view APIs but not call them.
+* **Administrators** - Manage API Management service instances and create the APIs, operations, and products that are used by developers. Azure subscription administrators are members of this group.
+* **Developers** - Authenticated developer portal users that build applications using your APIs. Developers are granted access to the developer portal and build applications that call the operations of an API.
+* **Guests** - Unauthenticated developer portal users. They can be granted certain read-only access, like the ability to view APIs but not call them.
 
-In addition to these system groups, administrators can create custom groups or leverage external groups in associated Azure Active Directory tenants. 
+In addition to these system groups, administrators can create custom groups or use external groups in associated Azure Active Directory tenants. 
 
 ## Developers
 
 Developers represent the user accounts in an API Management service instance. Developers can be created or invited to join by administrators, or they can sign up from the Developer portal. Each developer is a member of one or more groups, and can subscribe to the products that grant visibility to those groups.
 
 ## Policies
 
-Policies are a powerful capability of API Management that allow the Azure portal to change the behavior of the API through configuration. Policies are a collection of statements that are executed sequentially on the request or response of an API. Popular statements include format conversion from XML to JSON and call rate limiting to restrict the number of incoming calls from a developer, and many other policies are available.
+Policies are a collection of statements that are executed sequentially on the request or response of an API. Popular statements include format conversion from XML to JSON and call rate limiting to restrict the number of incoming calls from a developer, and many other policies are available.
 
-## Developer portal
+Policy expressions can be used as attribute values or text values in any of the API Management policies, unless the policy specifies otherwise. Some policies such as the Control flow and Set variable policies are based on policy expressions.
 
-The developer portal is where developers can learn about your APIs, view and call operations, and subscribe to products. Prospective customers can visit the developer portal, view APIs and operations, and sign up. The URL for your developer portal is located on the dashboard in the Azure portal for your API Management service instance.
+Policies can be applied at different scopes, depending on your needs: global (all APIs), a product, a specific API, or an API operation.
diff --git a/learn-pr/wwl-azure/explore-api-management/includes/3-api-gateways.md b/learn-pr/wwl-azure/explore-api-management/includes/3-api-gateways.md
@@ -1,32 +1,23 @@
 
-Your solution may contain several front- and back-end services. In this scenario, how does a client know what endpoints to call? What happens when new services are introduced, or existing services are refactored? How do services handle SSL termination, authentication, and other concerns? An *API gateway* can help to address these challenges.
+Your solution may contain several front- and back-end services. In this scenario, how does a client know what endpoints to call? What happens when new services are introduced, or existing services are refactored? How do services handle SSL termination, authentication, and other concerns? 
 
-:::image type="content" source="../media/api-gateway.png" alt-text="Diagram of an API gateway.":::
+The API Management gateway (also called data plane or runtime) is the service component that's responsible for proxying API requests, applying policies, and collecting telemetry.
 
-An API gateway sits between clients and services. It acts as a reverse proxy, routing requests from clients to services. It may also perform various cross-cutting tasks such as authentication, SSL termination, and rate limiting. If you don't deploy a gateway, clients must send requests directly to front-end services. However, there are some potential problems with exposing services directly to clients:
+An API gateway sits between clients and services. It acts as a reverse proxy, routing requests from clients to services. It may also perform various cross-cutting tasks such as authentication, SSL termination, and rate limiting. If you don't deploy a gateway, clients must send requests directly to back-end services. However, there are some potential problems with exposing services directly to clients:
 
 * It can result in complex client code. The client must keep track of multiple endpoints, and handle failures in a resilient way.
 * It creates coupling between the client and the backend. The client needs to know how the individual services are decomposed. That makes it harder to maintain the client and also harder to refactor services.
-* A single operation might require calls to multiple services. That can result in multiple network round trips between the client and the server, adding significant latency.
+* A single operation might require calls to multiple services. 
 * Each public-facing service must handle concerns such as authentication, SSL, and client rate limiting.
 * Services must expose a client-friendly protocol such as HTTP or WebSocket. This limits the choice of communication protocols.
 * Services with public endpoints are a potential attack surface, and must be hardened.
 
-A gateway helps to address these issues by decoupling clients from services. Gateways can perform a number of different functions, and you may not need all of them. The functions can be grouped into the following design patterns:
+A gateway helps to address these issues by decoupling clients from services.
 
-* **Gateway routing**: Use the gateway as a reverse proxy to route requests to one or more backend services, using layer 7 routing. The gateway provides a single endpoint for clients, and helps to decouple clients from services.
+## Managed and self-hosted
 
-* **Gateway aggregation**: Use the gateway to aggregate multiple individual requests into a single request. This pattern applies when a single operation requires calls to multiple backend services. The client sends one request to the gateway. The gateway dispatches requests to the various backend services, and then aggregates the results and sends them back to the client. This helps to reduce chattiness between the client and the backend.
+API Management offers both managed and self-hosted gateways:
 
-* **Gateway Offloading**: Use the gateway to offload functionality from individual services to the gateway, particularly cross-cutting concerns. It can be useful to consolidate these functions into one place, rather than making every service responsible for implementing them.
+* **Managed** - The managed gateway is the default gateway component that is deployed in Azure for every API Management instance in every service tier. With the managed gateway, all API traffic flows through Azure regardless of where backends implementing the APIs are hosted.
 
-Here are some examples of functionality that could be offloaded to a gateway:
-
-* SSL termination
-* Authentication
-* IP allow/block list
-* Client rate limiting (throttling)
-* Logging and monitoring
-* Response caching
-* GZIP compression
-* Servicing static content
+* **Self-hosted** - The self-hosted gateway is an optional, containerized version of the default managed gateway. It's useful for hybrid and multicloud scenarios where there's a requirement to run the gateways off of Azure in the same environments where API backends are hosted. The self-hosted gateway enables customers with hybrid IT infrastructure to manage APIs hosted on-premises and across clouds from a single API Management service in Azure.
diff --git a/learn-pr/wwl-azure/explore-api-management/includes/4-api-management-policies.md b/learn-pr/wwl-azure/explore-api-management/includes/4-api-management-policies.md
diff --git a/learn-pr/wwl-azure/explore-api-management/includes/8-exercise-import-api.md b/learn-pr/wwl-azure/explore-api-management/includes/8-exercise-import-api.md
diff --git a/learn-pr/wwl-azure/explore-api-management/index.yml b/learn-pr/wwl-azure/explore-api-management/index.yml
diff --git a/learn-pr/wwl-azure/explore-api-management/media/api-gateway.png b/learn-pr/wwl-azure/explore-api-management/media/api-gateway.png

Original file line number	Diff line number	Diff line change
`@@ -21789,6 +21789,11 @@`
`21789`	`21789`	`"source_path": "learn-pr/wwl-azure/work-with-cosmos-db/7-summary.md",`
`21790`	`21790`	`"redirect_url": "https://learn.microsoft.com/training/modules/work-with-cosmos-db/8-summary",`
`21791`	`21791`	`"redirect_document_id": false`
	`21792`	`+ },`
	`21793`	`+ {`
	`21794`	`+ "source_path": "learn-pr/wwl-azure/explore-api-management/8-import-api.md",`
	`21795`	`+ "redirect_url": "https://learn.microsoft.com/training/modules/explore-api-management/8-exercise-import-api",`
	`21796`	`+ "redirect_document_id": false`
`21792`	`21797`	`}`
`21793`	`21798`	`]`
`21794`	`21799`	`}`