Repository: kafka Updated Branches: refs/heads/0.10.0 86cce341b -> 9e2f067d1
KAFKA-3699: Update protocol page on website to explain how KIP-35 should be used â¦uld be used Author: Ashish Singh <[email protected]> Reviewers: Oleksiy Krivoshey <[email protected]>, Gwen Shapira <[email protected]>, Magnus Edenhill <[email protected]>, Dana Powers <[email protected]>, Ewen Cheslack-Postava <[email protected]> Closes #1395 from SinghAsDev/KAFKA-3699 (cherry picked from commit b1ba54025fc872e14e1ff97fde018637826a3a5e) Signed-off-by: Ewen Cheslack-Postava <[email protected]> Project: http://git-wip-us.apache.org/repos/asf/kafka/repo Commit: http://git-wip-us.apache.org/repos/asf/kafka/commit/9e2f067d Tree: http://git-wip-us.apache.org/repos/asf/kafka/tree/9e2f067d Diff: http://git-wip-us.apache.org/repos/asf/kafka/diff/9e2f067d Branch: refs/heads/0.10.0 Commit: 9e2f067d11be908b86e50a79c6cb2b5138168db0 Parents: 86cce34 Author: Ashish Singh <[email protected]> Authored: Tue Jun 14 09:49:54 2016 -0700 Committer: Ewen Cheslack-Postava <[email protected]> Committed: Tue Jun 14 09:50:47 2016 -0700 ---------------------------------------------------------------------- docs/protocol.html | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/kafka/blob/9e2f067d/docs/protocol.html ---------------------------------------------------------------------- diff --git a/docs/protocol.html b/docs/protocol.html index c26f16b..e28b0a8 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>
