Merge pull request #294858 from dlepow/wsuuf

[APIM][uuf] Update to websocket API

Author: prmerger-automator[bot]

articles/api-management/websocket-api.md

@@ -5,7 +5,7 @@ ms.service: azure-api-management
 author: dlepow
 ms.author: danlep
 ms.topic: how-to
-ms.date: 10/27/2022
+ms.date: 02/18/2025
 ms.custom: template-how-to
 ---
 
@@ -17,7 +17,7 @@ With API Management’s WebSocket API solution, API publishers can quickly add a
 
 [!INCLUDE [api-management-workspace-availability](../../includes/api-management-workspace-availability.md)]
 
-You can secure WebSocket APIs by applying existing access control policies, like [JWT validation](validate-jwt-policy.md). You can also test WebSocket APIs using the API test consoles in both Azure portal and developer portal. Building on existing observability capabilities, API Management provides metrics and logs for monitoring and troubleshooting WebSocket APIs. 
+WebSocket APIs can be secured by applying API Management's [access control policies](api-management-policies.md#authentication-and-authorization) to the initial handshake operation. You can also test WebSocket APIs using the API test consoles in both Azure portal and developer portal. Building on existing observability capabilities, API Management provides metrics and logs for monitoring and troubleshooting WebSocket APIs. 
 
 In this article, you will:
 > [!div class="checklist"]
@@ -39,25 +39,25 @@ API Management supports WebSocket passthrough.
 
 :::image type="content" source="./media/websocket-api/websocket-api-passthrough.png" alt-text="Visual illustration of WebSocket passthrough flow":::
 
-During the WebSocket passthrough the client application establishes a WebSocket connection with the API Management Gateway, which then establishes a connection with the corresponding backend services. API Management then proxies WebSocket client-server messages.
+During the WebSocket passthrough, the client application establishes a WebSocket connection with the API Management gateway, which then establishes a connection with the corresponding backend services. API Management then proxies WebSocket client-server messages.
 
-1. The client application sends a WebSocket handshake request to APIM gateway, invoking onHandshake operation.
-1. APIM gateway sends WebSocket handshake request to the corresponding backend service.
+1. The client application sends a WebSocket handshake request to the gateway, invoking the onHandshake operation
+1. The API Management gateway applies configured policies and sends WebSocket handshake requests to the corresponding backend service.
 1. The backend service upgrades a connection to WebSocket.
-1. APIM gateway upgrades the corresponding connection to WebSocket.
-1. Once the connection pair is established, APIM will broker messages back and forth between the client application and backend service.
-1. The client application sends message to APIM gateway.
-1. APIM gateway forwards the message to the backend service.
-1. The backend service sends a message to APIM gateway.
-1. APIM gateway forwards the message to the client application.
-1. When either side disconnects, APIM terminates the corresponding connection.
+1. The gateway upgrades the corresponding connection to WebSocket.
+1. After the connection pair is established, API Management brokers messages back and forth between the client application and backend service.
+1. The client application sends a message to the gateway.
+1. The gateway forwards the message to the backend service.
+1. The backend service sends a message to the gateway.
+1. The gateway forwards the message to the client application.
+1. When either side disconnects, API Management terminates the corresponding connection.
 
 > [!NOTE]
 > The client-side and backend-side connections consist of one-to-one mapping. 
 
 ## onHandshake operation
 
-Per the [WebSocket protocol](https://tools.ietf.org/html/rfc6455), when a client application tries to establish a WebSocket connection with a backend service, it will first send an [opening handshake request](https://tools.ietf.org/html/rfc6455#page-6). Each WebSocket API in API Management has an onHandshake operation. onHandshake is an immutable, unremovable, automatically created system operation. The onHandshake operation enables API publishers to intercept these handshake requests and apply API Management policies to them.
+Per the [WebSocket protocol](https://tools.ietf.org/html/rfc6455), when a client application tries to establish a WebSocket connection with a backend service, it first sends an [opening handshake request](https://tools.ietf.org/html/rfc6455#page-6). Each WebSocket API in API Management has an onHandshake operation. onHandshake is an immutable, unremovable, automatically created system operation. The onHandshake operation enables API publishers to intercept these handshake requests and apply API Management policies to them.
 
 :::image type="content" source="./media/websocket-api/onhandshake-screen.png" alt-text="onHandshake screen example":::
 
@@ -72,11 +72,11 @@ Per the [WebSocket protocol](https://tools.ietf.org/html/rfc6455), when a client
 
     | Field | Description |
     |----------------|-------|
-    | Display name | The name by which your WebSocket API will be displayed. |
+    | Display name | The name by which your WebSocket API is displayed. |
     | Name | Raw name of the WebSocket API. Automatically populates as you type the display name. |
     | WebSocket URL | The base URL with your websocket name. For example: *ws://example.com/your-socket-name* |
     | URL scheme | Accept the default |
-    | API URL suffix| Add a URL suffix to identify this specific API in this API Management instance. It has to be unique in this APIM instance. |
+    | API URL suffix| Add a URL suffix to identify this specific API in this API Management instance. It has to be unique in this API Management instance. |
     | Products | Associate your WebSocket API with a product to publish it. |
     | Gateways | Associate your WebSocket API with existing gateways. |
 
@@ -108,15 +108,15 @@ Use standard API Management and Azure Monitor features to [monitor](api-manageme
 * View API metrics in Azure Monitor
 * Optionally enable diagnostic settings to collect and view API Management gateway logs, which include WebSocket API operations
 
-For example, the following screenshot shows  recent WebSocket API responses with code `101` from the **ApiManagementGatewayLogs** table. These results indicate the successful switch of the requests from TCP to the WebSocket protocol.
+For example, the following screenshot shows recent WebSocket API responses with code `101` from the **ApiManagementGatewayLogs** table. These results indicate the successful switch of the requests from TCP to the WebSocket protocol.
 
 :::image type="content" source="./media/websocket-api/query-gateway-logs.png" alt-text="Query logs for WebSocket API requests":::
 
 ## Limitations
 
-Below are the current restrictions of WebSocket support in API Management:
+The following are the current restrictions of WebSocket support in API Management:
 
-* WebSocket APIs are not supported yet in the Consumption tier.
+* WebSocket APIs aren't supported yet in the Consumption tier.
 * WebSocket APIs support the following valid buffer types for messages: Close, BinaryFragment, BinaryMessage, UTF8Fragment, and UTF8Message.
 * Currently, the [set-header](set-header-policy.md) policy doesn't support changing certain well-known headers, including `Host` headers, in onHandshake requests.
 * During the TLS handshake with a WebSocket backend, API Management validates that the server certificate is trusted and that its subject name matches the hostname. With HTTP APIs, API Management validates that the certificate is trusted but doesn’t validate that hostname and subject match.
@@ -125,7 +125,7 @@ For WebSocket connection limits, see [API Management limits](../azure-resource-m
 
 ### Unsupported policies
 
-The following policies are not supported by and cannot be applied to the onHandshake operation:
+The following policies aren't supported by and can't be applied to the onHandshake operation:
 * Mock response
 * Get from cache
 * Store to cache
@@ -143,10 +143,10 @@ The following policies are not supported by and cannot be applied to the onHands
 * Validate status code
 
 > [!NOTE]
-> If you applied the policies at higher scopes (i.e., global or product) and they were inherited by a WebSocket API through the policy, they will be skipped at runtime.
+> If you applied the policies at higher scopes (for example, global or product) and they're inherited by a WebSocket API through the policy, they are skipped at runtime.
 
 [!INCLUDE [api-management-define-api-topics.md](../../includes/api-management-define-api-topics.md)]
 
-## Next steps
+## Related content
 > [!div class="nextstepaction"]
 > [Transform and protect a published API](transform-api.md)