Merge pull request #223135 from cebundy/wps-ref-review

[Web PubSub]: freshness review of reference articles

Author: Stacyrch140

articles/azure-web-pubsub/includes/reference-json-requests.md

@@ -18,7 +18,7 @@ Format:
 }
 ```
 
-* `ackId` is the identity of each request and should be unique. The service sends a [ack response message](#ack-response) to notify the process result of the request. More details can be found at [AckId and Ack Response](../concept-client-protocols.md#ackid-and-ack-response)
+* `ackId` is the identity of each request and should be unique. The service sends a [ack response message](#ack-response) to notify the process result of the request. For details, see  [AckId and Ack Response](../concept-client-protocols.md#ackid-and-ack-response)
 
 ### Leave groups
 
@@ -32,7 +32,7 @@ Format:
 }
 ```
 
-* `ackId` is the identity of each request and should be unique. The service sends a [ack response message](#ack-response) to notify the process result of the request. More details can be found at [AckId and Ack Response](../concept-client-protocols.md#ackid-and-ack-response)
+* `ackId` is the identity of each request and should be unique. The service sends a [ack response message](#ack-response) to notify the process result of the request. For details, see [AckId and Ack Response](../concept-client-protocols.md#ackid-and-ack-response)
 
 ### Publish messages
 
@@ -49,14 +49,15 @@ Format:
 }
 ```
 
-* `ackId` is the identity of each request and should be unique. The service sends a [ack response message](#ack-response) to notify the process result of the request. More details can be found at [AckId and Ack Response](../concept-client-protocols.md#ackid-and-ack-response)
-* `noEcho` is optional. If set to true, this message is not echoed back to the same connection. If not set, the default value is false.
-* `dataType` can be one of `json`, `text`, or `binary`:
+* `ackId` is the identity of each request and should be unique. The service sends a [ack response message](#ack-response) to notify the process result of the request. For details, see [AckId and Ack Response](../concept-client-protocols.md#ackid-and-ack-response)
+* `noEcho` is optional. If set to true, this message isn't echoed back to the same connection. If not set, the default value is false.
+* `dataType` can be set to `json`, `text`, or `binary`:
      * `json`: `data` can be any type that JSON supports and will be published as what it is; If `dataType` isn't specified, it defaults to `json`.
      * `text`: `data` should be in string format, and the string data will be published;
      * `binary`: `data` should be in base64 format, and the binary data will be published;
 
 #### Case 1: publish text data:
+
 ```json
 {
     "type": "sendToGroup",
@@ -67,7 +68,8 @@ Format:
 }
 ```
 
-* What subprotocol client in this group `<group_name>` receives:
+* The subprotocol clients in `<group_name>` receive:
+
 ```json
 {
     "type": "message",
@@ -77,9 +79,11 @@ Format:
     "data" : "text data"
 }
 ```
-* What the raw client in this group `<group_name>` receives is string data `text data`.
+
+* The simple WebSocket clients in `<group_name>` receive the string `text data`.
 
 #### Case 2: publish JSON data:
+
 ```json
 {
     "type": "sendToGroup",
@@ -91,7 +95,8 @@ Format:
 }
 ```
 
-* What subprotocol client in this group `<group_name>` receives:
+* The subprotocol clients in `<group_name>` receive:
+
 ```json
 {
     "type": "message",
@@ -103,10 +108,11 @@ Format:
     }
 }
 ```
-* What the raw client in this group `<group_name>` receives is serialized string data `{"hello": "world"}`.
 
+* The simple WebSocket clients in `<group_name>` receive the serialized string `{"hello": "world"}`.
 
 #### Case 3: publish binary data:
+
 ```json
 {
     "type": "sendToGroup",
@@ -117,7 +123,8 @@ Format:
 }
 ```
 
-* What subprotocol client in this group `<group_name>` receives:
+* The subprotocol clients in `<group_name>` receive:
+
 ```json
 {
     "type": "message",
@@ -127,7 +134,8 @@ Format:
     "data" : "<base64_binary>", 
 }
 ```
-* What the raw client in this group `<group_name>` receives is the **binary** data in the binary frame.
+
+* The simple WebSocket clients in `<group_name>` receive the **binary** data in the binary frame.
 
 ### Send custom events
 
@@ -143,14 +151,16 @@ Format:
 }
 ```
 
-* `ackId` is the identity of each request and should be unique. The service sends a [ack response message](#ack-response) to notify the process result of the request. More details can be found at [AckId and Ack Response](../concept-client-protocols.md#ackid-and-ack-response)
+* `ackId` is the identity of each request and should be unique. The service sends a [ack response message](#ack-response) to notify the process result of the request. For details, see [AckId and Ack Response](../concept-client-protocols.md#ackid-and-ack-response)
 
 `dataType` can be one of `text`, `binary`, or `json`:
-* `json`: data can be any type json supports and will be published as what it is; If `dataType` is not specified, it defaults to `json`.
-* `text`: data should be in string format, and the string data will be published;
-* `binary`: data should be in base64 format, and the binary data will be published;
+
+* `json`: data can be any type json supports and will be published as what it is; The default is `json`.
+* `text`: data is in string format, and the string data will be published;
+* `binary`: data is in base64 format, and the binary data will be published;
 
 #### Case 1: send event with text data:
+
 ```json
 {
     "type": "event",
@@ -161,7 +171,7 @@ Format:
 }
 ```
 
-What the upstream event handler receives like below, the `Content-Type` for the CloudEvents HTTP request is `text/plain` for `dataType`=`text`
+The upstream event handler receives data similar to:
 
 ```HTTP
 POST /upstream HTTP/1.1
@@ -184,6 +194,8 @@ text data
 
 ```
 
+The `Content-Type` for the CloudEvents HTTP request is `text/plain` when `dataType` is `text`.
+
 #### Case 2: send event with JSON data:
 ```json
 {
@@ -197,7 +209,7 @@ text data
 }
 ```
 
-What the upstream event handler receives like below, the `Content-Type` for the CloudEvents HTTP request is `application/json` for `dataType`=`json`
+The upstream event handler receives data similar to:
 
 ```HTTP
 POST /upstream HTTP/1.1
@@ -222,6 +234,8 @@ ce-eventName: <event_name>
 
 ```
 
+The `Content-Type` for the CloudEvents HTTP request is `application/json` when `dataType` is `json`
+
 #### Case 3: send event with binary data:
 ```json
 {
@@ -233,7 +247,7 @@ ce-eventName: <event_name>
 }
 ```
 
-What the upstream event handler receives like below, the `Content-Type` for the CloudEvents HTTP request is `application/octet-stream` for `dataType`=`binary`
+The upstream event handler receives data similar to:
 
 ```HTTP
 POST /upstream HTTP/1.1
@@ -256,6 +270,6 @@ binary
 
 ```
 
-The WebSocket frame can be `text` format for text message frames or UTF8 encoded binaries for `binary` message frames.
+The `Content-Type` for the CloudEvents HTTP request is `application/octet-stream` when `dataType` is `binary`.  The WebSocket frame can be `text` format for text message frames or UTF8 encoded binaries for `binary` message frames.
 
-Service declines the client if the message does not match the described format.
+The Web PubSub service declines the client if the message doesn't match the described format.

articles/azure-web-pubsub/includes/reference-permission.md

@@ -8,14 +8,14 @@ ms.date: 08/06/2021
 
 ## Permissions
 
-You may have noticed that when we describe the PubSub WebSocket clients, a client can publish to other clients only when it's *authorized* to. The `role`s of the client determines the *initial* permissions the client have:
+A PubSub WebSocket client can only publish to other clients when it's authorized. The `roles` assigned to the client determine the permissions granted to the client:
 
 | Role | Permission |
 |---|---|
 | Not specified | The client can send event requests.
 | `webpubsub.joinLeaveGroup` | The client can join/leave any group.
 | `webpubsub.sendToGroup` | The client can publish messages to any group.
-| `webpubsub.joinLeaveGroup.<group>` | The client can join/leave group `<group>`.
-| `webpubsub.sendToGroup.<group>` | The client can publish messages to group `<group>`.
+| `webpubsub.joinLeaveGroup.<group>` | The client can join/leave the group `<group>`.
+| `webpubsub.sendToGroup.<group>` | The client can publish messages to the group `<group>`.
 
-The server-side can also grant or revoke permissions of the client dynamically through REST APIs or server SDKs.
+The server can dynamically grant or revoke client permissions through REST APIs or server SDKs.

articles/azure-web-pubsub/includes/reference-protobuf-requests.md

@@ -18,23 +18,23 @@ Set `leave_group_message.group` to the group name.
 
 Format:
 
-* `ackId` is the identity of each request and should be unique. The service sends a [ack response message](#ack-response) to notify the process result of the request. More details can be found at [AckId and Ack Response](../concept-client-protocols.md#ackid-and-ack-response)
+* `ackId`:  The unique identity of each request. The service sends a [ack response message](#ack-response) to notify the process result of the request. More details can be found at [AckId and Ack Response](../concept-client-protocols.md#ackid-and-ack-response)
 
-There's an implicit `dataType`, which can be `protobuf`, `text`, or `binary`, depending on the `data` in `MessageData` you set. The receiver clients can use `dataType` to handle the content correctly.
+* `dataType`:  The data format, which can be `protobuf`, `text`, or `binary` depending on the `data` in `MessageData`. The receiving clients can use `dataType` to correctly process the content.
 
-* `protobuf`: If you set `send_to_group_message.data.protobuf_data`, the implicit `dataType` is `protobuf`. `protobuf_data` can be of the [Any](https://developers.google.com/protocol-buffers/docs/proto3#any) message type. All other clients receive a protobuf-encoded binary, which can be deserialized by the protobuf SDK. Clients that support only text-based content (for example, `json.webpubsub.azure.v1`) receive a Base64-encoded binary.
+* `protobuf`: When you set `send_to_group_message.data.protobuf_data`, the implicit `dataType` is `protobuf`. `protobuf_data` can be of the [Any](https://developers.google.com/protocol-buffers/docs/proto3#any) message type. All other clients receive a protobuf-encoded binary, which can be deserialized by the protobuf SDK. Clients that support only text-based content (for example, `json.webpubsub.azure.v1`) receive a Base64-encoded binary.
 
-* `text`: If you set `send_to_group_message.data.text_data`, the implicit `dataType` is `text`. `text_data` should be a string. All clients with other protocols receive a UTF-8-encoded string.
+* `text`: When you set `send_to_group_message.data.text_data`, the implicit `dataType` is `text`. `text_data` should be a string. All clients with other protocols receive a UTF-8-encoded string.
 
-* `binary`: If you set `send_to_group_message.data.binary_data`, the implicit `dataType` is `binary`. `binary_data` should be a byte array. All clients with other protocols receive a raw binary without protobuf encoding. Clients that support only text-based content (for example, `json.webpubsub.azure.v1`) receive a Base64-encoded binary.
+* `binary`: When you set `send_to_group_message.data.binary_data`, the implicit `dataType` is `binary`. `binary_data` should be a byte array. All clients with other protocols receive a raw binary without protobuf encoding. Clients that support only text-based content (for example, `json.webpubsub.azure.v1`) receive a Base64-encoded binary.
 
 #### Case 1: Publish text data
 
 Set `send_to_group_message.group` to `group`, and set `send_to_group_message.data.text_data` to `"text data"`.
 
 * The protobuf subprotocol client in group `group` receives the binary frame and can use [DownstreamMessage](#responses) to deserialize it.
 
-* The JSON subprotocol client in group `group` receives:
+* The JSON subprotocol clients in `group` receive:
 
     ```json
     {
@@ -46,11 +46,11 @@ Set `send_to_group_message.group` to `group`, and set `send_to_group_message.dat
     }
     ```
 
-* The raw client in group `group` receives string `text data`.
+* The simple WebSocket clients in `group` receive string `text data`.
 
 #### Case 2: Publish protobuf data
 
-Let's assume that you have a customer message:
+Let's assume that you have a custom message:
 
 ```
 message MyMessage {
@@ -60,9 +60,9 @@ message MyMessage {
 
 Set `send_to_group_message.group` to `group` and `send_to_group_message.data.protobuf_data` to `Any.pack(MyMessage)` with `value = 1`.
 
-* The protobuf subprotocol client in group `group` receives the binary frame and can use [DownstreamMessage](#responses) to deserialize it.
+* The protobuf subprotocol clients in `group` receive the binary frame and can use [DownstreamMessage](#responses) to deserialize it.
 
-* The subprotocol client in group `group` receives:
+* The subprotocol client in `group` receives:
 
     ```json
     {
@@ -87,7 +87,7 @@ message MyMessage {
 }
 ```
 
-* The raw client in group `group` receives the binary frame:
+* The simple WebSocket clients in `group` receive the binary frame:
 
     ```
     # Show in hexadecimal
@@ -114,7 +114,7 @@ Set `send_to_group_message.group` to `group`, and set `send_to_group_message.dat
 
     Because the JSON subprotocol client supports only text-based messaging, the binary is always Base64-encoded.
 
-* The raw client in group `group` receives the binary data in the binary frame:
+* The simple WebSocket clients in `group` receive the binary data in the binary frame:
 
     ```
     # Show in hexadecimal
@@ -125,17 +125,17 @@ Set `send_to_group_message.group` to `group`, and set `send_to_group_message.dat
 
 There's an implicit `dataType`, which can be `protobuf`, `text`, or `binary`, depending on the `dataType` you set. The receiver clients can use `dataType` to handle the content correctly.
 
-* `protobuf`: If you set `event_message.data.protobuf_data`, the implicit `dataType` is `protobuf`. `protobuf_data` can be any supported protobuf type. The event handler receives the protobuf-encoded binary, which can be deserialized by any protobuf SDK.
+* `protobuf`: When you set `event_message.data.protobuf_data`, the implicit `dataType` is `protobuf`. The `protobuf_data` value can be any supported protobuf type. The event handler receives the protobuf-encoded binary, which can be deserialized by any protobuf SDK.
 
-* `text`: If you set `event_message.data.text_data`, the implicit is `text`. `text_data` should be a string. The event handler receives a UTF-8-encoded string;
+* `text`: When you set `event_message.data.text_data`, the implicit `dataType` is `text`. The `text_data` value should be a string. The event handler receives a UTF-8-encoded string.
 
-* `binary`: If you set `event_message.data.binary_data`, the implicit is `binary`. `binary_data` should be a byte array. The event handler receives the raw binary frame.
+* `binary`: When you set `event_message.data.binary_data`, the implicit `dataType` is `binary`. The `binary_data` value should be a byte array. The event handler receives the simple WebSocket binary frame.
 
 #### Case 1: Send an event with text data
 
 Set `event_message.data.text_data` to `"text data"`.
 
-The upstream event handler receives a request that's similar to the following. Note that `Content-Type` for the CloudEvents HTTP request is `text/plain`, where `dataType`=`text`.
+The upstream event handler receives a request similar to: 
 
 ```HTTP
 POST /upstream HTTP/1.1
@@ -158,6 +158,8 @@ text data
 
 ```
 
+The `Content-Type` for the CloudEvents HTTP request is `text/plain`, where `dataType`=`text`.
+
 #### Case 2: Send an event with protobuf data
 
 Assume that you've received the following customer message:
@@ -170,7 +172,7 @@ message MyMessage {
 
 Set `event_message.data.protobuf_data` to `any.pack(MyMessage)` with `value = 1`
 
-The upstream event handler receives a request that's similar to the following. Note that the `Content-Type` for the CloudEvents HTTP request is `application/x-protobuf`, where `dataType`=`protobuf`.
+The upstream event handler receives a request that's similar to:
 
 ```HTTP
 POST /upstream HTTP/1.1
@@ -193,6 +195,8 @@ ce-eventName: <event_name>
 0A 2F 74 79 70 65 2E 67 6F 6F 67 6C 65 61 70 69 73 2E 63 6F 6D 2F 61 7A 75 72 65 2E 77 65 62 70 75 62 73 75 62 2E 54 65 73 74 4D 65 73 73 61 67 65 12 02 08 01
 ```
 
+The `Content-Type` for the CloudEvents HTTP request is `application/x-protobuf`, where `dataType`=`protobuf`.
+
 The data is a valid protobuf binary. You can use the following `proto` and `any.unpack()` to deserialize it:
 
 ```protobuf
@@ -207,7 +211,7 @@ message MyMessage {
 
 Set `send_to_group_message.binary_data` to `[1, 2, 3]`.
 
-The upstream event handler receives a request similar to the following. For `dataType`=`binary`, the `Content-Type` for the CloudEvents HTTP request is `application/octet-stream`. 
+The upstream event handler receives a request similar to: 
 
 ```HTTP
 POST /upstream HTTP/1.1
@@ -229,7 +233,6 @@ ce-eventName: <event_name>
 // Just show in hexadecimal; you need to read it as binary
 01 02 03 
 ```
-
-The WebSocket frame can be in `text` format for text message frames or UTF-8-encoded binaries for `binary` message frames.
+For `dataType`=`binary`, the `Content-Type` for the CloudEvents HTTP request is `application/octet-stream`.  The WebSocket frame can be in `text` format for text message frames or UTF-8-encoded binaries for `binary` message frames.
 
 The service declines the client if the message doesn't match the prescribed format.