Return-Path: X-Original-To: archive-asf-public-internal@cust-asf2.ponee.io Delivered-To: archive-asf-public-internal@cust-asf2.ponee.io Received: from cust-asf.ponee.io (cust-asf.ponee.io [163.172.22.183]) by cust-asf2.ponee.io (Postfix) with ESMTP id 39114200C06 for ; Fri, 27 Jan 2017 22:39:50 +0100 (CET) Received: by cust-asf.ponee.io (Postfix) id 37AE7160B5B; Fri, 27 Jan 2017 21:39:50 +0000 (UTC) Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by cust-asf.ponee.io (Postfix) with SMTP id 57EDA160B40 for ; Fri, 27 Jan 2017 22:39:49 +0100 (CET) Received: (qmail 5348 invoked by uid 500); 27 Jan 2017 21:39:48 -0000 Mailing-List: contact commits-help@kafka.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@kafka.apache.org Delivered-To: mailing list commits@kafka.apache.org Received: (qmail 5339 invoked by uid 99); 27 Jan 2017 21:39:48 -0000 Received: from git1-us-west.apache.org (HELO git1-us-west.apache.org) (140.211.11.23) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 27 Jan 2017 21:39:48 +0000 Received: by git1-us-west.apache.org (ASF Mail Server at git1-us-west.apache.org, from userid 33) id 39F78DFC31; Fri, 27 Jan 2017 21:39:48 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: ijuma@apache.org To: commits@kafka.apache.org Message-Id: <49b938062a144d2c878f044f8823f065@git.apache.org> X-Mailer: ASF-Git Admin Mailer Subject: kafka git commit: KAFKA-4664; Update docs/protocol.html with KIP-97 information Date: Fri, 27 Jan 2017 21:39:48 +0000 (UTC) archived-at: Fri, 27 Jan 2017 21:39:50 -0000 Repository: kafka Updated Branches: refs/heads/trunk 57f0cb299 -> 4a14adbb6 KAFKA-4664; Update docs/protocol.html with KIP-97 information Author: Colin P. Mccabe Reviewers: Gwen Shapira , Ismael Juma 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 Authored: Fri Jan 27 12:30:10 2017 +0000 Committer: Ismael Juma 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 @@

Versioning and Compatibility

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.

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.

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.

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.

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.

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.

Currently all versions are baselined at 0, as we evolve these APIs we will indicate the format for each version individually.

Retrieving Supported API versions

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 here. - 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.

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 KIP-35. + 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.

The following sequence may be used by a client to obtain supported API versions from a broker.

Client sends ApiVersionsRequest to a broker after connection has been established with the broker. If SSL is enabled, this happens after SSL connection has been established.
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.
Deprecation of a protocol version is done by marking an API version as deprecated in protocol documentation.
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 +
Deprecation of a protocol version is done by marking an API version as deprecated in the protocol documentation.
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.

SASL Authentication Sequence

The following sequence is used for SASL authentication: