Merge pull request #189697 from dlepow/sse

[APIM] Server-sent events (SSE)

Author: hmacgregor1

articles/api-management/TOC.yml

@@ -126,6 +126,8 @@
               href: how-to-configure-service-fabric-backend.md
             - name: Import SAP OData metadata
               href: sap-api.md
+            - name: Configure API for SSE
+              href: how-to-server-sent-events.md
       - name: Provision and scale
         items:
             - name: Capacity metric

articles/api-management/api-management-advanced-policies.md

@@ -245,7 +245,7 @@ This operation level policy does not forward requests to the backend service.
 | timeout="integer"                             | 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 as the underlying network infrastructure can drop idle connections after this time. | No       | None    |
 | follow-redirects="false | true"          | Specifies whether redirects from the backend service are followed by the gateway or returned to the caller.                                                                                                                                                                                                    | No       | false   |
 | buffer-request-body="false | true"       | When set to "true" request is buffered and will be reused on [retry](api-management-advanced-policies.md#Retry).                                                                                                                                                                                               | No       | false   |
-| buffer-response="false | true" | 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 (8KB, unless end of stream is detected) and only then returned to the caller. | No | true |
+| buffer-response="false &#124; true" | 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 (8KB, unless end of stream is detected) and only then returned to the caller.<br/><br/>Set to "false" with backends such as those implementing [server-sent events (SSE)](how-to-server-sent-events.md) that require content to be returned or streamed immediately to the caller. | No | true |
 | fail-on-error-status-code="false &#124; true" | When set to true triggers [on-error](api-management-error-handling-policies.md) section for response codes in the range from 400 to 599 inclusive.                                                                                                                                                                      | No       | false   |
 
 ### Usage

articles/api-management/how-to-server-sent-events.md

@@ -0,0 +1,50 @@
+---
+title: Configure API for server-sent events in Azure API Management 
+description: How to configure an API for server-sent events (SSE) in Azure API Management
+author: dlepow
+ms.service: api-management
+ms.topic: how-to
+ms.author: danlep
+ms.date: 02/24/2022
+---
+
+# Configure API for server-sent events
+
+This article provides guidelines for configuring an API in API Management that implements server-sent events (SSE). SSE is based on the HTML5 `EventSource` standard for streaming (pushing) data automatically to a client over HTTP after a client has established a connection.
+
+> [!TIP]
+> API Management also provides native support for [WebSocket APIs](websocket-api.md), which keep a single, persistent, bidrectional connection open between a client and server.
+
+## Prerequisites
+
+- An existing API Management instance. [Create one if you haven't already](get-started-create-service-instance.md).
+- An API that implements SSE. [Import and publish](import-and-publish.md) the API to your API Management instance using one of the supported import methods. 
+
+[!INCLUDE [premium-dev-standard-basic.md](../../includes/api-management-availability-premium-dev-standard-basic.md)]
+
+## Guidelines for SSE
+
+Follow these guidelines when using API Management to reach a backend API that implements SSE. 
+
+* **Choose service tier for long-running HTTP connections** - SSE relies on a long-running HTTP connection. Long-running connections are supported in the dedicated API Management tiers, but not in the Consumption tier.
+
+* **Keep idle connections alive** - If a connection between client and backend could be idle for 4 minutes or longer, implement a mechanism to keep the connection alive. For example, enable a TCP keepalive signal at the backend of the connection, or send traffic from the client side at least once per 4 minutes. 
+
+    This configuration is needed to override the idle session timeout of 4 minutes that is enforced by the Azure Load Balancer, which is used in the API Management infrastructure.
+
+* **Relay events immediately to clients** - Turn off response buffering on the [`forward-request` policy](api-management-advanced-policies.md#ForwardRequest) so that events are immediately relayed to the clients. For example:
+
+    ```xml
+    <forward-request timeout="120" fail-on-error-status-code="true" buffer-response="false"/>
+    ```
+
+* **Avoid other policies that buffer responses** - Certain policies such as [`validate-content`](validation-policies.md#validate-content) can also buffer response content and shouldn't be used with APIs that implement SSE.
+
+* **Disable response caching** - To ensure that notifications to the client are timely, verify that [response caching](api-management-howto-cache.md) isn't enabled. For more information, see [API Management caching policies](api-management-caching-policies.md).
+
+* **Test API under load** - Follow general practices to test your API under load to detect performance or configuration issues before going into production.  
+
+## Next steps
+
+* Learn more about [configuring policies](/api-management-howto-policies.md) in API Management.
+* Learn about API Management [capacity](api-management-capacity.md).