From b1ba54025fc872e14e1ff97fde018637826a3a5e Mon Sep 17 00:00:00 2001
From: Ashish Singh <asingh@cloudera.com>
Date: Tue, 14 Jun 2016 09:49:54 -0700
Subject: [PATCH] KAFKA-3699: Update protocol page on website to explain how
 KIP-35 should be used
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

…uld be used

Author: Ashish Singh <asingh@cloudera.com>

Reviewers: Oleksiy Krivoshey <oleksiy@luckyteam.co.uk>, Gwen Shapira <cshapi@gmail.com>, Magnus Edenhill <magnus@edenhill.se>, Dana Powers <dana.powers@gmail.com>, Ewen Cheslack-Postava <ewen@confluent.io>

Closes #1395 from SinghAsDev/KAFKA-3699
---
 docs/protocol.html | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/docs/protocol.html b/docs/protocol.html
index c26f16b464c..e28b0a8a617 100644
--- a/docs/protocol.html
+++ b/docs/protocol.html
@@ -114,6 +114,32 @@
 
 <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
+    may work against multiple broker versions, however to do so the clients need to know what versions of various APIs a
+    broker supports. Starting from 0.10.0.0, brokers provide information on various versions of APIs they support. Details
+    of this new capability can be found <a href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-35+-+Retrieving+protocol+version">here</a>.
+    Clients may use the supported API versions information to take appropriate actions such as propagating an unsupported
+    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>
+    <li>On receiving <code>ApiVersionsRequest</code>, a broker returns its full list of supported ApiKeys and
+        versions regardless of current authentication state (e.g., before SASL authentication on an SASL listener, do note that no
+        Kafka protocol requests may take place on a SSL listener before the SSL handshake is finished). If this is considered to
+        leak information about the broker version a workaround is to use SSL with client authentication which is performed at an
+        earlier stage of the connection where the <code>ApiVersionRequest</code> is not available. Also, note that broker versions older
+        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>Supported API versions obtained from a broker, is valid only for current 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
+        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>