kafka-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ij...@apache.org
Subject kafka git commit: KAFKA-4664; Update docs/protocol.html with KIP-97 information
Date Fri, 27 Jan 2017 21:39:48 GMT
Repository: kafka
Updated Branches:
  refs/heads/trunk 57f0cb299 -> 4a14adbb6


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


Project: http://git-wip-us.apache.org/repos/asf/kafka/repo
Commit: http://git-wip-us.apache.org/repos/asf/kafka/commit/4a14adbb
Tree: http://git-wip-us.apache.org/repos/asf/kafka/tree/4a14adbb
Diff: http://git-wip-us.apache.org/repos/asf/kafka/diff/4a14adbb

Branch: refs/heads/trunk
Commit: 4a14adbb63205e052b7620420b306e29320a4343
Parents: 57f0cb2
Author: Colin P. Mccabe <cmccabe@confluent.io>
Authored: Fri Jan 27 12:30:10 2017 +0000
Committer: Ismael Juma <ismael@juma.me.uk>
Committed: Fri Jan 27 21:39:27 2017 +0000

----------------------------------------------------------------------
 docs/protocol.html | 25 ++++++++++++-------------
 1 file changed, 12 insertions(+), 13 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/kafka/blob/4a14adbb/docs/protocol.html
----------------------------------------------------------------------
diff --git a/docs/protocol.html b/docs/protocol.html
index bd29905..5285f2e 100644
--- a/docs/protocol.html
+++ b/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
-    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>
+<p>In order to work against multiple broker versions, 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>.
+    Clients should use the supported API versions information to choose the highest API version
supported by both client and broker. If no such version
+    exists, an error should be reported to the user.</p>
+<p>The following sequence may be 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>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
+    <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 are only valid for the connection
on which that information is obtained.
+        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>


Mime
View raw message