[APIM] Circuit breaker in backend

Author: dlepow

articles/api-management/backends.md

@@ -8,7 +8,7 @@ editor: ''
 
 ms.service: api-management
 ms.topic: article
-ms.date: 09/21/2021
+ms.date: 07/24/2023
 ms.author: danlep 
 ms.custom:
 ---
@@ -26,12 +26,9 @@ 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. 
 
-Custom backends require extra configuration to authorize the credentials of requests to the backend service and define API operations. Configure and manage custom backends in the Azure portal, or using Azure APIs or tools.
+Custom backends require extra configuration, for example, to authorize the credentials of requests to the backend service and define API operations. Configure and manage custom backends in the Azure portal, or using Azure APIs or tools.
 
-After creating a backend, you can reference the backend in your APIs. Use the [`set-backend-service`](set-backend-service-policy.md) policy to redirect an incoming API request to the custom backend instead of the default backend for that API.
-
-> [!NOTE]
-> When you use the `set-backend-service` policy to redirect requests to a custom backend, refer to the backend by its name (`backend-id`), not by its URL.
+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.
 
 ## Benefits of backends
 
@@ -41,6 +38,94 @@ A custom backend has several benefits, including:
 * 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.
 
+
+## Circuit breaker property (preview)
+
+Starting in API version 2023-03-01 preview, API Management exposes a [circuit breaker](/rest/api/apimanagement/current-preview/backend/create-or-update?tabs=HTTP#backendcircuitbreaker) property in the backend resource to protect a backend service from being overwhelmed by too many requests.
+
+* The circuit breaker property defines rules to trip the circuit breaker, such as the number or percentage of failure conditions during a defined time interval and a range of status codes that indicate failures. 
+* When the circuit breaker trips, API Management stops sending requests to the backend service for a defined time, and returns a 503 Service Unavailable response to the client. 
+* After the configured trip duration, the circuit resets and traffic resumes to the backend.
+
+The backend circuit breaker is an implementation of the [circuit breaker pattern](/azure/architecture/patterns/circuit-breaker) to allow the backend to recover from overload situations. It augments general [rate-limiting](rate-limit-by-key.md) and [concurrency-limiting](limit-concurrency.md) policies that you can implement to protect the API Management gateway and your backend services.
+
+### Example
+
+Use the API Management REST API or a Bicep or ARM template to configure a circuit breaker in a backend. In the following example, the circuit breaker trips when there are three or more 5xx status codes indicating server errors in a day. The circuit breaker resets after one hour.
+
+#### [Bicep](#tab/bicep)
+
+Include a snippet similar to the following in your Bicep template:
+
+```bicep
+resource symbolicname 'Microsoft.ApiManagement/service/backends@2023-03-01-preview' = {
+  name: 'myBackend'
+  parent: resourceSymbolicName
+  properties: {
+    circuitBreaker: {
+      rules: [
+        {
+          failureCondition: {
+            count: 3
+            errorReasons: [
+              'Server errors'
+            ]
+            interval: 'P1D'
+            percentage: int
+            statusCodeRanges: [
+              {
+                max: 500
+                min: 599
+              }
+            ]
+          }
+          name: 'myBreakerRule'
+          tripDuration: 'P1H'
+        }
+      ]
+    }
+  }
+[...]
+}
+```
+
+#### [ARM](#tab/arm)
+
+Include a JSON snippet similar to the following in your ARM template:
+
+```JSON
+{
+  "type": "Microsoft.ApiManagement/service/backends",
+  "apiVersion": "2023-03-01-preview",
+  "name": "myBackend",
+  "properties": {
+    "circuitBreaker": {
+      "rules": [
+        {
+          "failureCondition": {
+            "count": "3",
+            "errorReasons": [ "Server errors" ],
+            "interval": "P1D",
+            "statusCodeRanges": [
+              {
+                "max": "500",
+                "min": "599"
+              }
+            ]
+          },
+          "name": "myBreakerRule",
+          "tripDuration": "P1H"
+        }
+      ]
+    },
+  }
+[...]
+}
+```
+
+---
+
+
 ## Limitation
 
 For **Developer** and **Premium** tiers, an API Management instance deployed in an [internal virtual network](api-management-using-with-internal-vnet.md) can throw HTTP 500 `BackendConnectionFailure` errors when the gateway endpoint URL and backend URL are the same. If you encounter this limitation, follow the instructions in the [Self-Chained API Management request limitation in internal virtual network mode](https://techcommunity.microsoft.com/t5/azure-paas-blog/self-chained-apim-request-limitation-in-internal-virtual-network/ba-p/1940417) article in the Tech Community blog.