Merge pull request #268545 from dlepow/cb

[APIM] Make backend LB and CB more discoverable

Author: prmerger-automator[bot]

articles/api-management/api-management-policies.md

@@ -5,7 +5,7 @@ services: api-management
 author: dlepow
 ms.service: api-management
 ms.topic: article
-ms.date: 12/01/2022
+ms.date: 03/08/2024
 ms.author: danlep
 ---
 
@@ -86,7 +86,7 @@ More information about policies:
 -   [Convert XML to JSON](xml-to-json-policy.md) - Converts request or response body from XML to JSON.
 -   [Find and replace string in body](find-and-replace-policy.md) - Finds a request or response substring and replaces it with a different substring.
 -   [Mask URLs in content](redirect-content-urls-policy.md) - Rewrites (masks) links in the response body so that they point to the equivalent link via the gateway.
--   [Set backend service](set-backend-service-policy.md) - Changes the backend service for an incoming request.
+-   [Set backend service](set-backend-service-policy.md) - Changes the backend service base URL of an incoming request to a URL or a [backend](backends.md). Referencing a backend resource allows you to manage the backend service base URL and other settings in a single place. Also implement [load balancing of traffic across a pool of backend services](backends.md#load-balanced-pool-preview) and [circuit breaker rules](backends.md#circuit-breaker-preview) to protect the backend from too many requests.
 - [Set body](set-body-policy.md) - Sets the message body for a request or response.
 -   [Set HTTP header](set-header-policy.md) - Assigns a value to an existing response and/or request header or adds a new response and/or request header.
 -   [Set query string parameter](set-query-parameter-policy.md) - Adds, replaces value of, or deletes request query string parameter.

articles/api-management/backends.md

@@ -1,11 +1,11 @@
 ---
 title: Azure API Management backends | Microsoft Docs
-description: Learn about custom backends in Azure API Management
+description: Learn about backends in Azure API Management. A backend entity encapsulates information about the backend service, promoting reusability across APIs and improved governance.
 services: api-management
 author: dlepow
 ms.service: api-management
 ms.topic: article
-ms.date: 01/09/2024
+ms.date: 03/14/2024
 ms.author: danlep 
 ms.custom:
 ---
@@ -23,25 +23,22 @@ API Management also supports using other Azure resources as an API backend, such
 * A [Service Fabric cluster](how-to-configure-service-fabric-backend.md).
 * A custom service. 
 
-API Management supports custom backends so you can manage the backend services of your API. Use custom backends for one or more of the following:
+## Benefits of backends
 
-* Authorize the credentials of requests to the backend service
-* Protect your backend from too many requests
-* Route or load-balance requests to multiple backends
+API Management supports backend entities so you can manage the backend services of your API. A backend entity encapsulates information about the backend service, promoting reusability across APIs and improved governance.
 
-Configure and manage custom backends in the Azure portal, or using Azure APIs or tools.
+Use backends for one or more of the following:
 
-## Benefits of backends
-
-A custom backend has several benefits, including:
+* Authorize the credentials of requests to the backend service
+* Take advantage of API Management functionality to maintain secrets in Azure Key Vault if [named values](api-management-howto-properties.md) are configured for header or query parameter authentication.
+* Define circuit breaker rules to protect your backend from too many requests
+* Route or load-balance requests to multiple backends
 
-* Abstracts information about the backend service, promoting reusability across APIs and improved governance.  
-* Easily used by configuring a transformation policy on an existing API.
-* Takes advantage of API Management functionality to maintain secrets in Azure Key Vault if [named values](api-management-howto-properties.md) are configured for header or query parameter authentication.
+Configure and manage backend entities in the Azure portal, or using Azure APIs or tools.
 
 ## Reference backend using set-backend-service policy
 
-After creating a backend, you can reference the backend in your APIs. Use the [`set-backend-service`](set-backend-service-policy.md) policy to direct an incoming API request to the custom backend. If you already configured a backend web service for an API, you can use the `set-backend-service` policy to redirect the request to a custom backend instead of the default backend web service configured for that API. For example:
+After creating a backend, you can reference the backend in your APIs. Use the [`set-backend-service`](set-backend-service-policy.md) policy to direct an incoming API request to the backend. If you already configured a backend web service for an API, you can use the `set-backend-service` policy to redirect the request to a backend entity instead. For example:
 
 ```xml
 <policies>

articles/api-management/high-availability.md

@@ -5,7 +5,7 @@ description: Learn how to use Azure reliability features including availability
 author: dlepow
 ms.service: api-management
 ms.topic: conceptual
-ms.date: 06/28/2023
+ms.date: 03/08/2024
 ms.author: danlep
 ms.custom: engagement-fy23
 ---
@@ -62,7 +62,11 @@ API Management provides an SLA of 99.99% when you deploy at least one unit in tw
 
 ## Backend availability
 
-Depending on where and how your backend services are hosted, you may need to set up redundant backends in different regions to meet your requirements for service availability. You can manage regional backends and handle failover through API Management to maintain availability. For example:  
+Depending on where and how your backend services are hosted, you may need to set up redundant backends in different regions to meet your requirements for service availability. You can also configure backend properties to improve the resilience and availability of your backend services.
+
+### Regional backends
+
+You can manage regional backends and handle failover through API Management to maintain availability. For example:  
 
 * In multi-region deployments, use [policies to route requests](api-management-howto-deploy-multi-region.md#-route-api-calls-to-regional-backend-services) through regional gateways to regional backends. 
 
@@ -72,6 +76,13 @@ Depending on where and how your backend services are hosted, you may need to set
 
 For details, see the blog post [Back-end API redundancy with Azure API Manager](https://devblogs.microsoft.com/premier-developer/back-end-api-redundancy-with-azure-api-manager/).
 
+### Configure backend properties for availability
+
+API Management [backend](backends.md) entities allow you to manage and apply backend properties to improve the availability of backends. For example:
+
+* Distribute and load-balance traffic to a [pool of URLs](backends.md#load-balanced-pool-preview)
+* Configure [circuit breaker rules](backends.md#circuit-breaker-preview) to apply the circuit breaker pattern to protect the backend from too many requests
+
 ## Next steps
 
 * Learn more about [reliability in Azure](../reliability/overview.md)

articles/api-management/set-backend-service-policy.md

@@ -6,13 +6,15 @@ author: dlepow
 
 ms.service: api-management
 ms.topic: article
-ms.date: 12/02/2022
+ms.date: 03/14/2024
 ms.author: danlep
 ---
 
 # Set backend service
 Use the `set-backend-service` policy to redirect an incoming request to a different backend than the one specified in the API settings for that operation. This policy changes the backend service base URL of the incoming request to a URL or [backend](backends.md) specified in the policy.
 
+Referencing a backend entity allows you to manage the backend service base URL and other settings in a single place and reuse them across multiple APIs and operations. Also implement [load balancing of traffic across a pool of backend services](backends.md#load-balanced-pool-preview) and [circuit breaker rules](backends.md#circuit-breaker-preview) to protect the backend from too many requests.
+
 > [!NOTE]
 > Backend entities can be managed via [Azure portal](how-to-configure-service-fabric-backend.md), management [API](/rest/api/apimanagement), and [PowerShell](https://www.powershellgallery.com/packages?q=apimanagement).