Repository: kafka Updated Branches: refs/heads/0.10.2 f328f77fd -> f0f5c3454
KAFKA-4664; Update docs/protocol.html with KIP-97 information Author: Colin P. Mccabe <[email protected]> Reviewers: Gwen Shapira <[email protected]>, Ismael Juma <[email protected]> Closes #2387 from cmccabe/KAFKA-4664 (cherry picked from commit 4a14adbb63205e052b7620420b306e29320a4343) Signed-off-by: Ismael Juma <[email protected]> Project: http://git-wip-us.apache.org/repos/asf/kafka/repo Commit: http://git-wip-us.apache.org/repos/asf/kafka/commit/f0f5c345 Tree: http://git-wip-us.apache.org/repos/asf/kafka/tree/f0f5c345 Diff: http://git-wip-us.apache.org/repos/asf/kafka/diff/f0f5c345 Branch: refs/heads/0.10.2 Commit: f0f5c345446fc7eb47c0acf48a862b501c6aaa4b Parents: f328f77 Author: Colin P. Mccabe <[email protected]> Authored: Fri Jan 27 12:30:10 2017 +0000 Committer: Ismael Juma <[email protected]> Committed: Fri Jan 27 21:39:54 2017 +0000 ---------------------------------------------------------------------- docs/protocol.html | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/kafka/blob/f0f5c345/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>
