KAFKA-4664; Update docs/protocol.html with KIP-97 information

Author: Colin P. Mccabe <cmccabe@confluent.io>

Reviewers: Gwen Shapira <cshapi@gmail.com>, Ismael Juma <ismael@juma.me.uk>

Closes #2387 from cmccabe/KAFKA-4664

docs/protocol.html

@@ -109,22 +109,22 @@
 
 <h5><a id="protocol_compatibility" href="#protocol_compatibility">Versioning and Compatibility</a></h5>
 
-<p>The protocol is designed to enable incremental evolution in a backward compatible fashion. Our versioning is on a per-api basis, each version consisting of a request and response pair. Each request contains an API key that identifies the API being invoked and a version number that indicates the format of the request and the expected format of the response.</p>
+<p>The protocol is designed to enable incremental evolution in a backward compatible fashion. Our versioning is on a per API basis, each version consisting of a request and response pair. Each request contains an API key that identifies the API being invoked and a version number that indicates the format of the request and the expected format of the response.</p>
 
-<p>The intention is that clients would implement a particular version of the protocol, and indicate this version in their requests. Our goal is primarily to allow API evolution in an environment where downtime is not allowed and clients and servers cannot all be changed at once.</p>
+<p>The intention is that clients will support a range of API versions. When communicating with a particular broker, a given client should use the highest API version supported by both and indicate this version in their requests.</p>
 
 <p>The server will reject requests with a version it does not support, and will always respond to the client with exactly the protocol format it expects based on the version it included in its request. The intended upgrade path is that new features would first be rolled out on the server (with the older clients not making use of them) and then as newer clients are deployed these new features would gradually be taken advantage of.</p>
 
+<p>Our goal is primarily to allow API evolution in an environment where downtime is not allowed and clients and servers cannot all be changed at once.</p>
+
 <p>Currently all versions are baselined at 0, as we evolve these APIs we will indicate the format for each version individually.</p>
 
 <h5><a id="api_versions" href="#api_versions">Retrieving Supported API versions</a></h5>
-<p>In order for a client to successfully talk to a broker, it must use request versions supported by the broker. Clients
+<p>In order to work against multiple broker versions, clients need to know what versions of various APIs a
-    may work against multiple broker versions, however to do so the clients need to know what versions of various APIs a
+    broker supports. The broker exposes this information since 0.10.0.0 as described in <a href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-35+-+Retrieving+protocol+version">KIP-35</a>.
-    broker supports. Starting from 0.10.0.0, brokers provide information on various versions of APIs they support. Details
+    Clients should use the supported API versions information to choose the highest API version supported by both client and broker. If no such version
-    of this new capability can be found <a href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-35+-+Retrieving+protocol+version">here</a>.
+    exists, an error should be reported to the user.</p>
-    Clients may use the supported API versions information to take appropriate actions such as propagating an unsupported
+<p>The following sequence may be used by a client to obtain supported API versions from a broker.</p>
-    API version error to application or choose an API request/response version supported by both the client and broker.
-    The following sequence maybe used by a client to obtain supported API versions from a broker.</p>
 <ol>
     <li>Client sends <code>ApiVersionsRequest</code> to a broker after connection has been established with the broker. If SSL is enabled,
         this happens after SSL connection has been established.</li>
@@ -136,13 +136,12 @@
         than 0.10.0.0 do not support this API and will either ignore the request or close connection in response to the request.</li>
     <li>If multiple versions of an API are supported by broker and client, clients are recommended to use the latest version supported
         by the broker and itself.</li>
-    <li>Deprecation of a protocol version is done by marking an API version as deprecated in protocol documentation.</li>
+    <li>Deprecation of a protocol version is done by marking an API version as deprecated in the protocol documentation.</li>
-    <li>Supported API versions obtained from a broker, is valid only for current connection on which that information is obtained.
+    <li>Supported API versions obtained from a broker are only valid for the connection on which that information is obtained.
-        In the event of disconnection, the client should obtain the information from broker again, as the broker might have
+        In the event of disconnection, the client should obtain the information from the broker again, as the broker might have been
         upgraded/downgraded in the mean time.</li>
 </ol>
 
-
 <h5><a id="sasl_handshake" href="#sasl_handshake">SASL Authentication Sequence</a></h5>
 <p>The following sequence is used for SASL authentication:
 <ol>