Edit

Share via

Forward request

APPLIES TO: All API Management tiers

The forward-request policy forwards the incoming request to the backend service specified in the request context. The backend service URL is specified in the API settings and can be changed using the set backend service policy.

Important

  • This policy is required to forward requests to an API backend. By default, API Management sets up this policy at the global scope.
  • Removing this policy results in the request not being forwarded to the backend service. Policies in the outbound section are evaluated immediately upon the successful completion of the policies in the inbound section.

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

<forward-request http-version="1 | 2or1 | 2" timeout="time in seconds (alternatively, use timeout-ms)" | timeout-ms="time in milliseconds (alternatively, use timeout)" continue-timeout="time in seconds" follow-redirects="false | true" buffer-request-body="false | true" buffer-response="true | false" fail-on-error-status-code="false | true"/>

Attributes

Attribute Description Required Default
timeout The amount of time in seconds to wait for the HTTP response headers to be returned by the backend service before a timeout error is raised. Minimum value is 0 seconds. Values greater than 240 seconds may not be honored, because the underlying network infrastructure can drop idle connections after this time. Policy expressions are allowed. You can specify either timeout or timeout-ms but not both. No 300
timeout-ms The amount of time in milliseconds to wait for the HTTP response headers to be returned by the backend service before a timeout error is raised. Minimum value is 0 ms. Policy expressions are allowed. You can specify either timeout or timeout-ms but not both. No N/A
continue-timeout The amount of time in seconds to wait for a 100 Continue status code to be returned by the backend service before a timeout error is raised. Policy expressions are allowed. No N/A
http-version The HTTP protocol version to use when sending the HTTP request to the backend service:
- 1: HTTP/1
- 2: HTTP/2
- 2or1: The gateway favors HTTP/2 over HTTP/1, but falls back to HTTP/1 if HTTP/2 doesn't work.

HTTP/2 outbound is supported in select gateways. See Usage notes for details.		 No 1
follow-redirects Specifies whether redirects from the backend service are followed by the gateway or returned to the caller. Policy expressions are allowed. No false
buffer-request-body When set to true, request is buffered and will be reused on retry. No false
buffer-response Affects processing of chunked responses. When set to false, each chunk received from the backend is immediately returned to the caller. When set to true, chunks are buffered (8 KB, unless end of stream is detected) and only then returned to the caller.

Set to false with backends such as those implementing server-sent events (SSE) that require content to be returned or streamed immediately to the caller. Policy expressions aren't allowed.		 No true
fail-on-error-status-code When set to true, triggers on-error section for response codes in the range from 400 to 599 inclusive. Policy expressions aren't allowed. No false

Usage

Usage notes

  • Use the http-version attribute to enable the HTTP/2 protocol outbound from the gateway to the backend. Set the attribute to 2or1 or 2. Currently, HTTP/2 outbound is supported in the self-hosted gateway and in preview in the v2 gateway.

    Important

    In the v2 gateway, HTTP/2 is supported inbound to the API Management gateway and outbound from the gateway to the backend but not end-to-end. Currently, the v2 gateway downgrades an incoming HTTP/2 connection to HTTP/1 before forwarding the request to the backend.

Examples

Send request to HTTP/2 backend

The following API level policy forwards all API requests to an HTTP/2 backend service. For example, use this policy to forward requests from a self-hosted gateway to a gRPC backend.

<!-- api level -->
<policies>
    <inbound>
        <base/>
    </inbound>
    <backend>
        <forward-request http-version="2or1"/>
    </backend>
    <outbound>
        <base/>
    </outbound>
</policies>

Forward request with timeout interval

The following API level policy forwards all API requests to the backend service with a timeout interval of 60 seconds.

<!-- api level -->
<policies>
    <inbound>
        <base/>
    </inbound>
    <backend>
        <forward-request timeout="60"/>
    </backend>
    <outbound>
        <base/>
    </outbound>
</policies>

Inherit policy from parent scope

This operation level policy uses the base element to inherit the backend policy from the parent API level scope.

<!-- operation level -->
<policies>
    <inbound>
        <base/>
    </inbound>
    <backend>
        <base/>
    </backend>
    <outbound>
        <base/>
    </outbound>
</policies>

Do not inherit policy from parent scope

This operation level policy explicitly forwards all requests to the backend service with a timeout of 120 and doesn't inherit the parent API level backend policy. If the backend service responds with an error status code from 400 to 599 inclusive, on-error section will be triggered.

<!-- operation level -->
<policies>
    <inbound>
        <base/>
    </inbound>
    <backend>
        <forward-request timeout="120" fail-on-error-status-code="true" />
        <!-- effective policy. note the absence of <base/> -->
    </backend>
    <outbound>
        <base/>
    </outbound>
</policies>

Do not forward requests to backend

This operation level policy doesn't forward requests to the backend service.

<!-- operation level -->
<policies>
    <inbound>
        <base/>
    </inbound>
    <backend>
        <!-- no forwarding to backend -->
    </backend>
    <outbound>
        <base/>
    </outbound>
</policies>

Related content

For more information about working with policies, see: