Streaming requests and responses

You're viewingApigee Edge documentation.
Go to theApigee X documentation.info

What you'll learn in this topic

After reading this topic you will know:

  • What request and response streaming on Apigee Edge is
  • When to use request and response streaming
  • How to enable request and response streaming
Sample: If you'd like to jump directly to a code sample, see "Related code samples" for details.

What is request and response streaming?

By default, HTTP streaming is disabled and HTTP request and response payloads are written to a buffer in memory before they are processed by the API proxy pipeline. You can change this behavior by enabling streaming. With streaming enabled, request and response payloads are streamed without modification to the client app (for responses) and the target endpoint (for requests).

When should I enable streaming?

If your API proxy handles very large requests and/or responses (for size limits, seeWhat else should I know about streaming below), you may want to enable streaming.

Note: If your API requests or returns a large amount of data, you may see this HTTP error:
{"fault":"{\"detail\":{\"errorcode\":\"protocol.http.TooBigBody\"},\"faultstring\":\"Body buffer overflow\"}"}

If you see this error, we recommend that you enable streaming. If you continue to see the error after you enable streaming, consider removing any policies that require access to the request or response payload. For more information, see "Message payload size" inBest practices for API proxy design and development.

What else should I know about streaming?

Message payload size is restricted to 10 MB in Edge Cloud and Private Cloud, even with streaming enabled. In non-streamed requests and responses, exceeding that size results in aprotocol.http.TooBigBody error.

While streaming can help you work around the 10 MB request/response size limit enforced by the product, Apigee doesn't recommend exceeding that limit when streaming and can't support issues that arise as a result of exceeding that limit, such as performance issues, timeouts, and so on. If you receive a timeout or gateway error, seeError message reference for possible troubleshootingsteps.

For payloads larger than 10 MB, Apigee recommends using a signed URLs pattern within an Apigee JavaCallout, illustrated by the Edge Callout: Signed URL Generator example on GitHub.

In Edge for Private Cloud deployments, you can modify the non-streamed request/response size limit. Be sure to test before deploying the change to production.

  • For Edge for Private Cloud releases previous to 4.16.01:

    On all Message Processors, edit thehttp.properties file to increase the limit in theHTTPResponse.body.buffer.limit parameter and then restart the Message Processor.
  • For Edge for Private Cloud release 4.16.01 and later:

    1. Edit the file/<inst_root>/apigee/customer/application/message-processor.properties. If that file does not exist, create it.

    2. Set theconf_http_HTTPResponse.body.buffer.limit property inmessage-processor.properties. For example:
      conf_http_HTTPResponse.body.buffer.limit=5m

    3. Restart the Message Processor:
      > /<inst_root>/apigee/apigee-service/bin/apigee-service edge-message-processor restart

    4. Repeat for all Message Processors.

With streaming enabled, Apigee strongly recommends you donot attach policies that require access to the request or response payload. Those types of policies will either cause errors or trigger buffering in the API proxy, which limits payload size to the numbers listed above and defeats the purpose of enabling streaming to handle large payloads. You can attach policies that do not interact with the request/response body, such as authentication or message logging policies.

How to enable request and response streaming

To enable request streaming you need to add therequest.streaming.enabled property to the ProxyEndpoint and TargetEndpoint definitions in the proxy bundle and set it totrue. Similarly, set theresponse.streaming.enabled property to enable response streaming.

You can locate these configuration files in the management UI in the Develop view for your proxy. If you are developing locally, these definition files are inapiproxy/proxies andapiproxy/targets.

This sample shows how to enable both request and response streaming in the TargetEndpoint definition.

<TargetEndpoint name="default">  <HTTPTargetConnection>    <URL>http://mocktarget.apigee.net</URL>    <Properties>      <Property name="response.streaming.enabled">true</Property>      <Property name="request.streaming.enabled">true</Property>      <Property name="supports.http10">true</Property>      <Property name="request.retain.headers">User-Agent,Referer,Accept-Language</Property>      <Property name="retain.queryparams">apikey</Property>    </Properties>  </HTTPTargetConnection></TargetEndpoint>

This example shows how to enable response and request streaming in the ProxyEndpoint definition:

<ProxyEndpoint name="default">  <HTTPProxyConnection>    <BasePath>/v1/weather</BasePath>    <Properties>      <Property name="allow.http10">true</Property>      <Property name="response.streaming.enabled">true</Property>      <Property name="request.streaming.enabled">true</Property>    </Properties>  </HTTPProxyConnection></ProxyEndpoint>

For more information about configuring endpoint definitions, seeEndpoint properties reference.

Related code samples

API proxy samples on GitHub are easy to download and use. SeeUsing the sample API proxies for information about downloading and using the samples.

Sample proxies that feature streaming include:

  • streaming - Demonstrates an API proxy configured for HTTP streaming.
  • Edge Callout: Signed URL Generator - Illustrates the best practice of generating a signed URL to access large files instead of trying to stream them in a request/response.

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-02 UTC.