Endpoint properties reference

This pageapplies toApigee andApigee hybrid.

View Apigee Edge documentation.

This topic describes transport properties that can be set inTargetEndpoint andProxyEndpoint configurations to control messaging and connection behavior. For full coverage of theTargetEndpoint andProxyEndpoint configuration options, seeAPI proxy configuration reference.

TargetEndpoint Transport Properties

TheHTTPTargetConnection element inTargetEndpoint configurations defines a set of HTTP transport properties. You can use these properties to set transport-level configurations.

Properties are set onTargetEndpointHTTPTargetConnection 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>
Note: Property values can only be literals. You cannot set values using variables.

TargetEndpoint Transport Property Specification

Property NameDefault ValueDescription
allow.post.without.content.lengthfalseLets you send POST requests with no content in the body.
allow.put.without.content.lengthfalseLets you send PUT requests with no content in the body.
allow.tls.session.resumptiontrueIftrue (the default) clients reuse TLS sessions when making new connections to the target. Set tofalse 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.millis60000Connection 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 HTTP503 status code if a connection timeout occurs. In some cases an HTTP504 status code may be returned whenLoadBalancer is used in theTargetServer definition and a timeout occurs.

Note: In some cases, Apigee will automatically retry the connection up to three times. As a result, the total retry time may exceed what is configured forconnect.timeout.millis.
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.millis55000

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.

  • If a timeout happens while reading the HTTP request from ingress,408 Request Timeout is retuned.408 Request Timeout will not be returned if a timeout happens while writing a request to the target.
  • If a timeout happens while writing the HTTP request or reading the HTTP response,504 Gateway Timeout is returned.

SeeSetting io.timeout.millis and api.timeout.

supports.http11trueIf this istrue and the client sends a1.1 request, the target is also sent a1.1 request, otherwise1.0 request is sent to the target.
use.proxytrue

If the Apigee hybrid overrides file contains theHTTP_PROXY configuration, as described inConfigure forward proxying for API proxies, then use this property to manage/control which proxies should not use the proxy configuration.

If set tofalse, the API Proxy will skip the HTTP proxy configurations specified in the Apigee hybrid overrides file for target connections set in the proxy.

use.proxy.tunnelingtrue

If this is set to true, and proxy configurations are specified Apigee hybrid overrides file as described inConfigure 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.

use.proxy.host.header.with.target.uritrue

Sets the target host and port as aHost header. By default, the proxy host and port are set asHost headers. You can only set this property in the Target Endpoint. For example:

  <HTTPTargetConnection>    <Properties>        <Property name="use.proxy.host.header.with.target.uri">true</Property>    </Properties>    <URL>https://mocktarget.apigee.net/my-target</URL>  </HTTPTargetConnection>

response.payload.
parse.limit		10MBy default (10M). Use the propertyresponse.payload.parse.limit to set the maximum payload size that can be processed in the response flow, in megabytes (M). The minimum configurable limit is 10M and the maximum configurable limit is 30M. If the property is not set, the default limit is 10M.

See alsoMessage payload size.

request.streaming.enabledfalse

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 totrue. Whentrue, HTTP request payloads are not read into a buffer; they are streamed as-is to the target endpoint. In this case, any policies that operate on the payload in theTargetEndpoint request flow are bypassed. See alsoStreaming requests and responses.

response.streaming.enabledfalse

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 theProxyEndpoint response flow. In this case, any policies that operate on the payload in theTargetEndpoint response flow are bypassed. See alsoStreaming requests and responses.

success.codesN/A

By default, Apigee treats HTTP code4XX or5XX as errors, and it treats HTTP code1XX,2XX,3XX as success. This property enables explicit definition of success codes, for example,2XX, 1XX, 505 treats any100,200 and505 HTTP response codes as success.

Setting this property overwrites the default values. Therefore, if you want to add HTTP code400 to the list of default success codes, set this property as:

<Property name="success.codes">1xx,2xx,3xx,400</Property>

If you want only HTTP code400 to be treated as a success code, set the property as:

<Property name="success.codes">400</Property>

By setting HTTP code400 as the only success code, the codes1xx,2xx, and3xx are treated as failures.

compression.algorithmN/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:
  • gzip: always send message using gzip compression
  • deflate: always send message using deflate compression
  • none: always send message without any compression

See also:Does Apigee support compression/de-compression with GZIP/deflate compression?

request.retain.headers.
enabled		trueBy default, Apigee always retains all HTTP headers on outbound messages. When set totrue, all HTTP headers present on the inbound request are set on the outbound request.
request.retain.headersN/ADefines specific HTTP headers from the request that should be set on the outbound request to the target service. For example, topassthrough theUser-Agent header, set the value ofrequest.retain.headers toUser-Agent. Multiple HTTP headers are specified as a comma-separated list, for example,User-Agent,Referer,Accept-Language. This property overridesrequest.retain.headers.enabled. Ifrequest.retain.headers.enabled is set tofalse, any headers specified in therequest.retain.headers property are still set on the outbound message.
response.retain.headers.
enabled		trueBy default, Apigee always retains all HTTP headers on outbound messages. When set totrue, all HTTP headers present on the inbound response from the target service are set on the outbound response before it is passed to theProxyEndpoint.
response.retain.headersN/ADefines specific HTTP headers from the response that should be set on the outbound response before it is passed to theProxyEndpoint. For example, topassthrough theExpires header, set the value ofresponse.retain.headers toExpires. Multiple HTTP headers are specified as a comma-separated list, for example,Expires,Set-Cookie. This property overridesresponse.retain.headers.enabled. Ifresponse.retain.headers.enabled is set tofalse, any headers specified in theresponse.retain.headers property are still set on the outbound message.
retain.queryparams.
enabled		trueBy default, Apigee always retains all query parameters on outbound requests. When set totrue, all query parameters present on the inbound request are set on the outbound request to the target service.
retain.queryparamsN/ADefines specific query parameters to set on the outbound request. For example, to include the query parameterapikey from the request message, setretain.queryparams toapikey. Multiple query parameters are specified as a comma-separated list, for example,apikey,environment. This property overridesretain.queryparams.enabled.

ProxyEndpoint Transport Properties

ProxyEndpointHTTPTargetConnection elements define a set of HTTP transport properties. These properties can be used to set transport-level configurations.

Properties are set onProxyEndpointHTTPProxyConnection 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 theX-Apigee-* pattern are removed from incoming requests if a client sends them. This name pattern is reserved for Apigee.

ProxyEndpoint Transport Property Specification

Property NameDefault ValueDescription
X-Forwarded-ForfalseWhen set to true, the virtual host's IP address is added to the outbound request as the value of the HTTPX-Forwarded-For header.
request.streaming.
enabled		falseBy 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 totrue. Whentrue, HTTP request payloads are not read into a buffer; they are streamed as-is to theTargetEndpoint request flow. In this case, any policies that operate on the payload in theProxyEndpoint request flow are bypassed. See alsoStreaming requests and responses.
request.payload.
parse.limit		10MBy default (10M). Use the propertyrequest.payload.parse.limit to set the maximum payload size that can be processed in the request flow, in megabytes (M). The minimum configurable limit is 10M and the maximum configurable limit is 30M. If the property is not set, the default limit is 10M.

See alsoMessage payload size.

response.streaming.
enabled		falseBy 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 totrue. Whentrue, 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 theProxyEndpoint response flow are bypassed. See alsoStreaming requests and responses.
compression.algorithmN/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 theTargetEndpoint orProxyEndpoint. Supported values are:

  • gzip: always send message using gzip compression
  • deflate: always send message using deflate compression
  • none: always send message without any compression

See also:Does Apigee support compression/de-compression with GZIP/deflate compression?

api.timeoutN/A

Configure the timeout for individual API proxies (in milliseconds)

You can configure API proxies, even those withstreaming enabled, to time out after a specified time with a504 Gateway Timeout status.

Important:The specified timeout must be shorter than the standard Message Processor timeout of 300 seconds.

For example, to configure a proxy to time out after 180000 milliseconds (three minutes), add the following property toHTTPProxyConnection:

<Property name="api.timeout">180000</Property>

You cannot set this property with a variable.

SeeSetting io.timeout.millis and api.timeout.

HTTPHeader.allowDuplicatesN/A

Use this setting to allow duplicate headers (for specific headers).

<HTTPProxyConnection>  <Properties>     <Property name="HTTPHeader.allowDuplicates">Content-Type,Authorization</Property>  </Properties></HTTPProxyConnection>
HTTPHeader.multiValuedN/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 ofio.timeout.millis andapi.timeout are related. On every request to an API proxy:

  1. 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.
  2. The Message Processor then setsapi.timeout:
    1. Ifapi.timeout isnot set at the proxy level, use the timeout set by the Ingress.
    2. Ifapi.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.

  3. The value ofapi.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 a504 Gateway Timeout.

  4. The value ofio.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.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-19 UTC.