Merge pull request #110250 from dagiro/freshness35

freshness35

Author: ShannonLeavitt

articles/hdinsight/kafka/rest-proxy.md

@@ -1,36 +1,37 @@
 ---
 title: Apache Kafka REST proxy - Azure HDInsight
-description: Learn how to perform Apache Kafka operations using a Kafka REST proxy on Azure HDInsight.
+description: Learn how to do Apache Kafka operations using a Kafka REST proxy on Azure HDInsight.
 author: hrasheed-msft
 ms.author: hrasheed
 ms.reviewer: hrasheed
 ms.service: hdinsight
 ms.topic: conceptual
-ms.date: 04/01/2020
+ms.date: 04/03/2020
 ---
+
 # Interact with Apache Kafka clusters in Azure HDInsight using a REST proxy
 
-Kafka REST Proxy enables you to interact with your Kafka cluster via a REST API over HTTP. This means that your Kafka clients can be outside of your virtual network. Additionally, clients can make simple HTTP calls to send and receive messages to the Kafka cluster, instead of relying on Kafka libraries. This tutorial will show you how to create a REST proxy enabled Kafka cluster and provide a sample code that shows how to make calls to REST proxy.
+Kafka REST Proxy enables you to interact with your Kafka cluster via a REST API over HTTP. This action means that your Kafka clients can be outside of your virtual network. Clients can make simple HTTP calls to the Kafka cluster, instead of relying on Kafka libraries. This article will show you how to create a REST proxy enabled Kafka cluster. Also provides a sample code that shows how to make calls to REST proxy.
 
 ## REST API reference
 
-For the full specification of operations supported by the Kafka REST API, see [HDInsight Kafka REST Proxy API Reference](https://docs.microsoft.com/rest/api/hdinsight-kafka-rest-proxy).
+For operations supported by the Kafka REST API, see [HDInsight Kafka REST Proxy API Reference](https://docs.microsoft.com/rest/api/hdinsight-kafka-rest-proxy).
 
 ## Background
 
-![Kafka REST proxy architecture](./media/rest-proxy/rest-proxy-architecture.png)
+![Kafka REST proxy design](./media/rest-proxy/rest-proxy-architecture.png)
 
-For the full specification of operations supported by the API, please see [Apache Kafka REST Proxy API](https://docs.microsoft.com/rest/api/hdinsight-kafka-rest-proxy).
+For the full specification of operations supported by the API, see [Apache Kafka REST Proxy API](https://docs.microsoft.com/rest/api/hdinsight-kafka-rest-proxy).
 
 ### REST Proxy endpoint
 
-Creating an HDInsight Kafka cluster with REST proxy creates a new public endpoint for your cluster, which you can find in your HDInsight cluster "Properties" on the Azure portal.
+Creating an HDInsight Kafka cluster with REST proxy creates a new public endpoint for your cluster, which you can find in your HDInsight cluster **Properties** on the Azure portal.
 
 ### Security
 
-Access to the Kafka REST proxy is managed with Azure Active Directory security groups. When creating the Kafka cluster with the REST proxy enabled, you'll provide the Azure Active Directory security group that should have access to the REST endpoint. The Kafka clients (applications) that need access to the REST proxy should be registered to this group by the group owner. The group owner can do this via the Portal or via PowerShell.
+Access to the Kafka REST proxy is managed with Azure Active Directory security groups. When creating the Kafka cluster, provide the Azure AD security group with REST endpoint access. Kafka clients that need access to the REST proxy should be registered to this group by the group owner. The group owner can register via the Portal or via PowerShell.
 
-Before making requests to the REST proxy endpoint, the client application should get an OAuth token to verify membership of the right security group. Find a [Client application sample](#client-application-sample) below that shows how to get an OAuth token. Once the client application has the OAuth token, they must pass that token in the HTTP request made to the REST proxy.
+For REST proxy endpoint requests, client applications should get an OAuth token. The token is used to verify security group membership. Find a [Client application sample](#client-application-sample) below that shows how to get an OAuth token. The client application passes the OAuth token in the HTTP request to the REST proxy.
 
 > [!NOTE]  
 > See [Manage app and resource access using Azure Active Directory groups](../../active-directory/fundamentals/active-directory-manage-groups.md), to learn more about AAD security groups. For more information on how OAuth tokens work, see [Authorize access to Azure Active Directory web applications using the OAuth 2.0 code grant flow](../../active-directory/develop/v1-protocols-oauth-code.md).
@@ -39,17 +40,17 @@ Before making requests to the REST proxy endpoint, the client application should
 
 1. Register an application with Azure AD. The client applications that you write to interact with the Kafka REST proxy will use this application's ID and secret to authenticate to Azure.
 
-1. Create an Azure AD security group and add the application that you've registered with Azure AD to the security group as a "member" of the group. This security group will be used to control which applications are allowed to interact with the REST proxy. For more information on creating Azure AD groups, see [Create a basic group and add members using Azure Active Directory](../../active-directory/fundamentals/active-directory-groups-create-azure-portal.md).
+1. Create an Azure AD security group. Add the application that you've registered with Azure AD to the security group as a **member** of the group. This security group will be used to control which applications are allowed to interact with the REST proxy. For more information on creating Azure AD groups, see [Create a basic group and add members using Azure Active Directory](../../active-directory/fundamentals/active-directory-groups-create-azure-portal.md).
 
-    Validate the group is of type "Security"
+    Validate the group is of type **Security**.
     ![Security Group](./media/rest-proxy/rest-proxy-group.png)
 
-    Validate that application is member of Group
-    ![Validate Membership](./media/rest-proxy/rest-proxy-membergroup.png)
+    Validate that application is member of Group.
+    ![Check Membership](./media/rest-proxy/rest-proxy-membergroup.png)
 
 ## Create a Kafka cluster with REST proxy enabled
 
-1. During the Kafka cluster creation workflow, in the "Security + networking" tab, check the "Enable Kafka REST proxy" option.
+1. During the Kafka cluster creation workflow, in the **Security + networking** tab, check the **Enable Kafka REST proxy** option.
 
      ![Enable Kafka REST proxy and select security group](./media/rest-proxy/azure-portal-cluster-security-networking-kafka-rest.png)
 
@@ -69,19 +70,23 @@ You can use the python code below to interact with the REST proxy on your Kafka
 
 1. Save the sample code on a machine with Python installed.
 1. Install required python dependencies by executing `pip3 install adal` and `pip install msrestazure`.
-1. Modify the code section *Configure these properties* and update the following properties for your environment:
-    1.    *Tenant ID* – The Azure tenant where your subscription is.
-    1.    *Client ID* – The ID for the application that you registered in the security group.
-    1.    *Client Secret* – The secret for the application that you registered in the security group
-    1.    *Kafkarest_endpoint* – get this value from the "properties" tab in the cluster overview as described in the [deployment section](#create-a-kafka-cluster-with-rest-proxy-enabled). It should be in the following format – `https://<clustername>-kafkarest.azurehdinsight.net`
+1. Modify the code section **Configure these properties** and update the following properties for your environment:
+
+    |Property |Description |
+    |---|---|
+    |Tenant ID|The Azure tenant where your subscription is.|
+    |Client ID|The ID for the application that you registered in the security group.|
+    |Client Secret|The secret for the application that you registered in the security group.|
+    |Kafkarest_endpoint|Get this value from the **Properties** tab in the cluster overview as described in the [deployment section](#create-a-kafka-cluster-with-rest-proxy-enabled). It should be in the following format – `https://<clustername>-kafkarest.azurehdinsight.net`|
+
 1. From the command line, execute the python file by executing `python <filename.py>`
 
-This code does the following:
+This code does the following action:
 
-1. Fetches an OAuth token from Azure AD
-1. Shows how to make a request to Kafka REST proxy
+1. Fetches an OAuth token from Azure AD.
+1. Shows how to make a request to Kafka REST proxy.
 
-For more information on getting OAuth tokens in python, see [Python AuthenticationContext class](https://docs.microsoft.com/python/api/adal/adal.authentication_context.authenticationcontext?view=azure-python). You might see a delay while topics that aren't created or deleted through the Kafka REST proxy are reflected there. This delay is due to cache refresh.
+For more information on getting OAuth tokens in python, see [Python AuthenticationContext class](https://docs.microsoft.com/python/api/adal/adal.authentication_context.authenticationcontext?view=azure-python). You might see a delay while `topics` that aren't created or deleted through the Kafka REST proxy are reflected there. This delay is because of cache refresh.
 
 ```python
 #Required python packages