Backends in API Management

  • Article

APPLIES TO: All API Management tiers

A backend (or API backend) in API Management is an HTTP service that implements your front-end API and its operations.

When importing certain APIs, API Management configures the API backend automatically. For example, API Management configures the backend web service when importing:

API Management also supports using other Azure resources as an API backend, such as:

Benefits of 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.

Use backends for one or more of the following:

  • 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 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

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 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:

<policies>
    <inbound>
        <base />
        <set-backend-service backend-id="myBackend" />
    </inbound>
    [...]
<policies/>

You can use conditional logic with the set-backend-service policy to change the effective backend based on location, gateway that was called, or other expressions.

For example, here is a policy to route traffic to another backend based on the gateway that was called:

<policies>
    <inbound>
        <base />
        <choose>
            <when condition="@(context.Deployment.Gateway.Id == "factory-gateway")">
                <set-backend-service backend-id="backend-on-prem" />
            </when>
            <when condition="@(context.Deployment.Gateway.IsManaged == false)">
                <set-backend-service backend-id="self-hosted-backend" />
            </when>
            <otherwise />
        </choose>
    </inbound>
    [...]
<policies/>

Circuit breaker

API Management exposes a circuit breaker 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 to allow the backend to recover from overload situations. It augments general rate-limiting and concurrency-limiting policies that you can implement to protect the API Management gateway and your backend services.

Note

  • Currently, the backend circuit breaker isn't supported in the Consumption tier of API Management.
  • Because of the distributed nature of the API Management architecture, circuit breaker tripping rules are approximate. Different instances of the gateway do not synchronize and will apply circuit breaker rules based on the information on the same instance.
  • Currently, only one rule can be configured for a backend circuit breaker.

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 in myBackend in the API Management instance myAPIM trips when there are three or more 5xx status codes indicating server errors in 1 hour.

The circuit breaker resets after 1 hour. If a Retry-After header is present in the response, the circuit breaker accepts the value and waits for the specified time before sending requests to the backend again.

Include a snippet similar to the following in your Bicep template for a backend resource with a circuit breaker:

resource symbolicname 'Microsoft.ApiManagement/service/backends@2023-09-01-preview' = {
  name: 'myAPIM/myBackend'
  properties: {
    url: 'https://mybackend.com'
    protocol: 'http'
    circuitBreaker: {
      rules: [
        {
          failureCondition: {
            count: 3
            errorReasons: [
              'Server errors'
            ]
            interval: 'PT1H' 
            statusCodeRanges: [
              {
                min: 500
                max: 599
              }
            ]
          }
          name: 'myBreakerRule'
          tripDuration: 'PT1H'  
          acceptRetryAfter: true
        }
      ]
    }
   }
 }

Load-balanced pool

API Management supports backend pools, when you want to implement multiple backends for an API and load-balance requests across those backends.

Use a backend pool for scenarios such as the following:

  • Spread the load to multiple backends, which may have individual backend circuit breakers.
  • Shift the load from one set of backends to another for upgrade (blue-green deployment).

To create a backend pool, set the type property of the backend to pool and specify a list of backends that make up the pool.

Note

  • Currently, you can only include single backends in a backend pool. You can't add a backend of type pool to another backend pool. You can include up to 30 backends in a pool.
  • Because of the distributed nature of the API Management architecture, backend load balancing is approximate. Different instances of the gateway do not synchronize and will load balance based on the information on the same instance.

Load balancing options

API Management supports the following load balancing options for backend pools:

  • Round-robin: By default, requests are distributed evenly across the backends in the pool.
  • Weighted: Weights are assigned to the backends in the pool, and requests are distributed across the backends based on the relative weight assigned to each backend. Use this option for scenarios such as conducting a blue-green deployment.
  • Priority-based: Backends are organized in priority groups, and requests are sent to the backends in order of the priority groups. Within a priority group, requests are distributed either evenly across the backends, or (if assigned) according to the relative weight assigned to each backend.

Note

Backends in lower priority groups will only be used when all backends in higher priority groups are unavailable because circuit breaker rules are tripped.

Example

Use the API Management REST API or a Bicep or ARM template to configure a backend pool. In the following example, the backend myBackendPool in the API Management instance myAPIM is configured with a backend pool. Example backends in the pool are named backend-1 and backend-2. Both backends are in the highest priority group; within the group, backend-1 has a greater weight than backend-2 .

Include a snippet similar to the following in your Bicep template for a backend resource with a load-balanced pool:

resource symbolicname 'Microsoft.ApiManagement/service/backends@2023-09-01-preview' = {
  name: 'myAPIM/myBackendPool'
  properties: {
    description: 'Load balancer for multiple backends'
    type: 'Pool'
    pool: {
      services: [
        {
          id: '/subscriptions/<subscriptionID>/resourceGroups/<resourceGroupName>/providers/Microsoft.ApiManagement/service/<APIManagementName>/backends/backend-1'
          priority: 1
          weight: 3
        }
        {
          id: '/subscriptions/<subscriptionID>/resourceGroups/<resourceGroupName>/providers/Microsoft.ApiManagement/service/<APIManagementName>/backends/backend-2'
          priority: 1
          weight: 1
        }
      ]
    }
  }
}

Limitations

Related content