Send Docs Feedback

Note: Most user interface tasks can be performed in Edge Classic or the New Edge experience. For an overview, getting started topics, and release notes specific to the New Edge experience, see the docs.

Streaming requests and responses

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

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, see "What else should I know about streaming" below), you may wish to enable streaming. For example, you may wish to enable a streaming response flow if you have a Node.js application deployed on Edge that returns output over time, such as a Comet-style application. Or, you may wish to enable streaming for any application that accepts or returns a very large amount of data. 

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" in Best practices for API proxy design and development.

What else should I know about streaming?

Message payload size is restricted to the following. Exceeding those sizes results in a protocol.http.TooBigBody error.

  • 10MB in Edge Cloud
  • 10MB in Edge for Private Cloud

In Edge for Private Cloud deployments, you can modify this value. 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 the file to increase the limit in the HTTPResponse.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/ If that file does not exist, create it.

    2. Set the conf_http_HTTPResponse.body.buffer.limit property in For example:

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

    4. Repeat for all Message Processors.

We strongly recommend you do not attach policies where streaming is enabled (request or response). If policies are attached, buffering can occur that limits payload size to the numbers listed above, which defeats the purpose of enabling streaming to handle large payloads.

How to enable response and request streaming

To enable request streaming you need to add the request.streaming.enabled property to the ProxyEndpoint and TargetEndpoint definitions in the proxy bundle and set it to true. Similarly, set the response.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 in apiproxy/proxies and apiproxy/targets

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

<TargetEndpoint name="default">
      <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>

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

<ProxyEndpoint name="default">
      <Property name="allow.http10">true</Property>
      <Property name="response.streaming.enabled">true</Property>
      <Property name="request.streaming.enabled">true</Property>

For more information about configuring endpoint definitions, see Endpoint properties reference.

Related code samples

API proxy samples on GitHub are easy to download and use. See Using 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. 


Help or comments?