Edit

Share via

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.

Create a backend

You can create a backend in the Azure portal, or using Azure APIs or tools.

To create a backend in the portal:

  1. Sign into the portal and go to your API Management instance.
  2. In the left menu, select APIs > Backends > + Create new backend.
  3. On the Backend page, do the following:
    1. Enter a Name for the backend and optional Description.
    2. Select a Backend hosting type, for example, Azure resource for an Azure resource such as a Function App or Logic App, Custom URL for a custom service, or a Service Fabric cluster.
    3. In Runtime URL, enter the URL of the backend service that API requests are forwarded to.
    4. Under Advanced, optionally disable certificate chain or certificate name validation for the backend.
    5. Under Add this backend service to a backend pool, optionally select or create a load-balanced pool for the backend.
    6. Under Circuit breaker rule, optionally configure a circuit breaker for the backend.
    7. Under Authorization credentials, optionally configure credentials to authorize access to the backend. Options include a request header, query parameter, client certificate, or system-assigned or user-assigned managed identity configured in the API Management instance.
    8. Select Create.

After creating a backend, you can update the backend settings at any time. For example, add a circuit breaker rule, change the runtime URL, or add authorization credentials.

Configure managed identity for authorization credentials

You can use a system-assigned or user-assigned managed identity configured in the API Management instance to authorize access to the backend service. To configure a managed identity for authorization credentials, do the following:

  1. In the Authorization credentials section of the backend configuration, select the Managed identity tab, and select Enable.

  2. In Client identity, select either System assigned identity or a user-assigned identity that is configured in your instance.

  3. In Resource ID, enter a target Azure service or the application ID of your own Microsoft Entra application representing the backend. Example: https://cognitiveservices.azure.com for Azure OpenAI service.

    For more examples, see the authentication-managed-identity policy reference.

  4. Select Create.

Note

Also assign the managed identity the appropriate permissions or an RBAC role to access the backend service. For example, if the backend is an Azure OpenAI service, you might assign the managed identity the Cognitive Services User role.

Reference backend using set-backend-service policy

After creating a backend, you can reference the backend identifier (name) 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/>

Note

Alternatively, you can use base-url. Usually, the format is https://backend.com/api. Avoid adding a slash at the end to prevent misconfigurations. Typically, the base-url and HTTP(S) endpoint value in the backend should match to enable seamless integration between frontend and backend. Note that API Management instances append the backend service name to the base-url.

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 Azure portal, 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 in this example 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.

  1. In the Azure portal, go to your API Management instance.
  2. In the left menu, select APIs > Backends > your backend.
  3. In the backend page, select Settings > Circuit breaker settings > Add new.
  4. In the Create new circuit breaker page, configure the rule:
    • Rule name: Enter a name for the rule, such as myBackend.
    • Failure count: Enter 3.
    • Failure interval: Leave the default value of 1 hour.
    • Failure status code range: Select 500 - 599.
    • Trip duration: Leave the default value of 1 hour.
    • Check 'Retry-After' header in HTTP response: Select True (Accept).

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. A pool is a collection of backends that are treated as a single entity for load balancing.

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).

Note

  • 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 portal, 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 .

  1. In the Azure portal, go to your API Management instance.
  2. In the left menu, select APIs > Backends > your backend.
  3. In the Backends page, select the Load balancer tab.
  4. Select + Create new pool.
  5. In the Create new load-balanced pool page, do the following:
    • Name: Enter a name for the pool such as myBackendPool.
    • Description: Optionally enter a description.
    • Add backends to pool: Select one or more backends to add to the pool.
    • Backend weight and priority: Select Customize weight and priority to configure the weight and priority of each backend in the pool. For example, if you added two backends named backend-1 and backend-2, set the weight of backend-1 to 3 and the weight of backend-2 to 1, and set the priority of both backends to 1.
    • Select Create.

Limitations

Related content