Edit

Share via

Set backend service

  • Article

APPLIES TO: All API Management tiers

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 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 and circuit breaker rules to protect the backend from too many requests.

Note

Backend entities can be managed via Azure portal, management API, and PowerShell.

Note

Set the policy's elements and child elements in the order provided in the policy statement. Learn more about how to set or edit API Management policies.

Policy statement

XML 
<set-backend-service base-url="base URL of the backend service"  backend-id="name of the backend entity specifying base URL of the backend service" sf-resolve-condition="condition" sf-service-instance-name="Service Fabric service name" sf-listener-name="Service Fabric listener name" />

Attributes

Attribute Description Required Default
base-url New backend service base URL. Policy expressions are allowed. One of base-url or backend-id must be present. N/A
backend-id Identifier (name) of the backend to route primary or secondary replica of a partition. Policy expressions are allowed. One of base-url or backend-id must be present. N/A
sf-resolve-condition Only applicable when the backend is a Service Fabric service. Condition identifying if the call to Service Fabric backend has to be repeated with new resolution. Policy expressions are allowed. No N/A
sf-service-instance-name Only applicable when the backend is a Service Fabric service. Allows changing service instances at runtime. Policy expressions are allowed. No N/A
sf-partition-key Only applicable when the backend is a Service Fabric service. Specifies the partition key of a Service Fabric service. Policy expressions are allowed. No N/A
sf-listener-name Only applicable when the backend is a Service Fabric service and is specified using backend-id. Service Fabric Reliable Services allows you to create multiple listeners in a service. This attribute is used to select a specific listener when a backend Reliable Service has more than one listener. If this attribute isn't specified, API Management will attempt to use a listener without a name. A listener without a name is typical for Reliable Services that have only one listener. Policy expressions are allowed. No N/A

Usage

Usage notes

Currently, if you define a base set-backend-service policy using the backend-id attribute and inherit the base policy using <base /> within the scope, then it can only be overridden with a policy using the backend-id attribute, not the base-url attribute.

Examples

Route request based on value in query string

In this example the set-backend-service policy routes requests based on the version value passed in the query string to a different backend service than the one specified in the API.

XML 
<policies>
    <inbound>
        <choose>
            <when condition="@(context.Request.Url.Query.GetValueOrDefault("version") == "2013-05")">
                <set-backend-service base-url="http://contoso.com/api/8.2/" />
            </when>
            <when condition="@(context.Request.Url.Query.GetValueOrDefault("version") == "2014-03")">
                <set-backend-service base-url="http://contoso.com/api/9.1/" />
            </when>
        </choose>
        <base />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

Initially the backend service base URL is derived from the API settings. So the request URL https://contoso.azure-api.net/api/partners/15?version=2013-05&subscription-key=abcdef becomes http://contoso.com/api/10.4/partners/15?version=2013-05&subscription-key=abcdef where http://contoso.com/api/10.4/ is the backend service URL specified in the API settings.

When the <choose> policy statement is applied the backend service base URL may change again either to http://contoso.com/api/8.2 or http://contoso.com/api/9.1, depending on the value of the version request query parameter. For example, if the value is "2013-15" the final request URL becomes http://contoso.com/api/8.2/partners/15?version=2013-15&subscription-key=abcdef.

If further transformation of the request is desired, other Transformation policies can be used. For example, to remove the version query parameter now that the request is being routed to a version specific backend, the Set query string parameter policy can be used to remove the now redundant version attribute.

Route requests to a service fabric backend

In this example the policy routes the request to a service fabric backend, using the userId query string as the partition key and using the primary replica of the partition.

XML 
<policies>
    <inbound>
        <set-backend-service backend-id="my-sf-service" sf-partition-key="@(context.Request.Url.Query.GetValueOrDefault("userId","")" sf-replica-type="primary" />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

Related content

For more information about working with policies, see: