This page applies to Apigee and Apigee hybrid.
View Apigee Edge documentation.
This topic describes transport properties that can be set in TargetEndpoint
and ProxyEndpoint
configurations to control messaging and connection behavior. For full coverage of
the TargetEndpoint
and ProxyEndpoint
configuration options, see API proxy configuration reference.
TargetEndpoint Transport Properties
The HTTPTargetConnection
element in TargetEndpoint
configurations
defines a set of HTTP
transport properties. You can use these properties to set transport-level configurations.
Properties are set on TargetEndpoint
HTTPTargetConnection
elements
as shown in this example configuration:
<TargetEndpoint name="default"> <HTTPTargetConnection> <URL>http://mocktarget.apigee.net</URL> <Properties> <Property name="request.retain.headers">User-Agent,Referer,Accept-Language</Property> <Property name="retain.queryparams">apikey</Property> </Properties> </HTTPTargetConnection> </TargetEndpoint>
TargetEndpoint Transport Property Specification
Property Name | Default Value | Description |
---|---|---|
allow.post.without.content.length |
false | Lets you send POST requests with no content in the body. |
allow.put.without.content.length |
false | Lets you send PUT requests with no content in the body. |
allow.tls.session.resumption |
true | If true (the default) clients reuse TLS sessions when making new connections to the target.
Set to false if you do not want TLS session reuse. Session reuse generally
means shorter connection times, but some targets may not support session reuse or have
difficulty with it. |
keepalive.timeout.millis |
60000 | Connection idle timeout for the target connection in the connection pool. If the connection in the pool is idle beyond the specified limit, then the connection is closed. |
connect.timeout.millis |
3000 |
Target connection timeout. Apigee returns an HTTP |
ignore.allow.header.for.405 |
true |
Lets you pass the 405 status code back to the client. By enabling the flag Apigee will return 405 instead of 502 status code. |
io.timeout.millis |
55000 |
If there is no data to read for the specified number of milliseconds, or if the socket is not ready to write data for a specified number of milliseconds, then the transaction is treated as a timeout.
|
supports.http11 |
true | If this is true and the client sends a 1.1 request, the target is also sent a
1.1
request, otherwise 1.0 request is sent to the target. |
use.proxy |
true |
If the Apigee hybrid overrides file contains the
If set to |
use.proxy.tunneling |
true |
If this is set to true, and proxy configurations are specified Apigee hybrid overrides file as described in Configure forward proxying for API proxies, then target connections are set to use the specified tunnel. If the target uses TLS/SSL, then this property is ignored, and the message is always sent using a tunnel. |
request.streaming.enabled |
false |
By default ( |
response.streaming.enabled |
false |
By default (false), HTTP response payloads are read into a buffer, and policies that
can operate on the payload work as expected. In cases where the payloads are larger than
the buffer size (10 MB in Apigee), you can set this
attribute to true. When true, HTTP response payloads are not read into a buffer; they are
streamed as-is to the |
success.codes |
N/A |
By default, Apigee treats HTTP code Setting this property overwrites the default values. Therefore, if you want to add
HTTP code
If you want only HTTP code
By setting HTTP code |
compression.algorithm |
N/A |
By default, Apigee honors the compression type set (gzip, deflate or none) for messages
received. If the request is received from the client using, for example, gzip
compression, then Apigee forwards the request to the target using gzip compression. If
the response received from target uses deflate, then Apigee forwards the response to
the client using deflate. Supported values are:
See also: Does Apigee support compression/de-compression with GZIP/deflate compression? |
request.retain.headers. |
true | By default, Apigee always retains all HTTP headers on outbound messages. When set
to true , all HTTP headers present on the inbound request are set on the
outbound request. |
request.retain.headers |
N/A | Defines specific HTTP headers from the request that should be set on the outbound
request to the target service. For example, to passthrough the User-Agent
header, set the value of request.retain.headers to User-Agent .
Multiple HTTP headers are specified as a comma-separated list, for example,
User-Agent,Referer,Accept-Language . This property overrides
request.retain.headers.enabled . If request.retain.headers.enabled
is set to false , any headers specified in the
request.retain.headers property are still set on the outbound message. |
response.retain.headers. |
true | By default, Apigee always retains all HTTP headers on outbound messages. When set
to true , all HTTP headers present on the inbound response from the target
service are set on the outbound response before it is passed to the
ProxyEndpoint . |
response.retain.headers |
N/A | Defines specific HTTP headers from the response that should be set on the outbound
response before it is passed to the ProxyEndpoint . For example, to
passthrough the
Expires header, set the value of response.retain.headers to
Expires . Multiple HTTP headers are specified as a comma-separated list, for
example, Expires,Set-Cookie . This property overrides
response.retain.headers.enabled . If
response.retain.headers.enabled is set to false , any headers
specified in the response.retain.headers property are still set on the
outbound message. |
retain.queryparams. |
true | By default, Apigee always retains all query parameters on outbound requests. When
set to true , all query parameters present on the inbound request are set on
the outbound request to the target service. |
retain.queryparams |
N/A | Defines specific query parameters to set on the outbound request. For example, to
include the query parameter apikey from the request message, set
retain.queryparams to apikey . Multiple query parameters are
specified as a comma-separated list, for example, apikey,environment . This
property overrides retain.queryparams.enabled . |
ProxyEndpoint Transport Properties
ProxyEndpoint
HTTPTargetConnection
elements define a set of HTTP
transport properties. These
properties can be used to set transport-level configurations.
Properties are set on ProxyEndpoint
HTTPProxyConnection
elements
as shown in this example configuration:
<ProxyEndpoint name="default"> <HTTPProxyConnection> <BasePath>/v1/weather</BasePath> <Properties> <Property name="request.streaming.enabled">true</Property> </Properties> </HTTPProxyConnection> </ProxyEndpoint>
Request headers
An incoming HTTP request includes the HTTP headers sent by the client.
Headers with names that match the X-Apigee-*
pattern are removed from incoming
requests if a client sends them. This name pattern is reserved for Apigee.
ProxyEndpoint Transport Property Specification
Property Name | Default Value | Description |
---|---|---|
X-Forwarded-For |
false | When set to true, the virtual host's IP address is added to the outbound request as the
value of the HTTP X-Forwarded-For header. |
request.streaming. |
false |
By default (false ), HTTP request payloads are read into a buffer, and
policies that can
operate on the payload work as expected. In cases where the payloads are larger than the
buffer size (10 MB in Apigee), you can set this
attribute to true . When true , HTTP request payloads are not read
into a buffer; they are
streamed as-is to the TargetEndpoint request flow. In this case, any policies
that operate
on the payload in the ProxyEndpoint request flow are bypassed. See also
Streaming requests and
responses. |
response.streaming. |
false |
By default (false), HTTP response payloads are read into a buffer, and policies that
can operate on the payload work as expected. In cases where the payloads are larger than
the buffer size (10 MB in Apigee), you can set this
attribute to true . When true , HTTP response payloads are not read
into a buffer; they are
streamed as-is to the client. In this case, any policies that operate on the payload in the
ProxyEndpoint response flow are bypassed. See also
Streaming requests and
responses. |
compression.algorithm |
N/A |
By default, Apigee honors the compression type set (gzip, deflate or none) for messages received. For
example, where a client submits a request that uses gzip compression, Apigee
forwards the request to the target using gzip compression. You can configure compression
algorithms to be explicitly applied by setting this property on the
See also: Does Apigee support compression/de-compression with GZIP/deflate compression? |
api.timeout |
N/A |
Configure the timeout for individual API proxies (in milliseconds) You can configure API proxies, even those with
streaming enabled,
to time out after a specified time with a
For example, to configure a proxy to time out after 180000 milliseconds (three minutes),
add the following property to <Property name="api.timeout">180000</Property> You cannot set this property with a variable. |
HTTPHeader.allowDuplicates |
N/A | Use this setting to allow duplicate headers (for specific headers). <HTTPProxyConnection> <Properties> <Property name="HTTPHeader.allowDuplicates">Content-Type,Authorization</Property> </Properties> </HTTPProxyConnection> |
HTTPHeader.multiValued |
N/A | Use this setting to allow duplicate headers (for specific headers). <HTTPProxyConnection> <Properties> <Property name="HTTPHeader.multiValued">Content-Type,Authorization</Property> </Properties> </HTTPProxyConnection> |
Setting io.timeout.millis and api.timeout
The operation of io.timeout.millis
and api.timeout
are related. On every request to an API proxy:
- The Ingress (aka Internal Load Balancer) sends its timeout value to the Message Processor. This timeout value defaults to 300 seconds and is not configurable.
- The Message Processor then sets
api.timeout
:- If
api.timeout
is not set at the proxy level, use the timeout set by the Ingress. - If
api.timeout
is set at the proxy level, set it on the Message Processor to the lesser of the Ingress timeout or the value ofapi.timeout
.
- If
-
The value of
api.timeout
specifies the maximum amount of time an API proxy has to execute from the API request to the response.After each policy in the API proxy executes, or before the Message Processor sends the request to the target endpoint, the Message Processor calculates (
api.timeout
- elapsed time from the start of the request).If the value is less than zero, then the maximum amount of time to handle the request has expired and the Message Processor returns a
504 Gateway Timeout
. -
The value of
io.timeout.millis
specifies the maximum amount of time that the target endpoint has to respond.Before connecting to a target endpoint, the Message Processor determines the lesser of (
api.timeout
- elapsed time from the start of the request) andio.timeout.millis
. It then setsio.timeout.millis
to that value.If a timeout happens while writing the HTTP request or reading the HTTP response,
504 Gateway Timeout
is returned.