This page is meant as a template for writing a KIP. To create a KIP choose Tools->Copy on this page and modify with your content and replace the heading with the next KIP number and a description of your issue. Replace anything in italics with your own description.

Status

Current state: DraftDiscarded

Discussion thread: here [Change the link from the KIP proposal email archive to your own email thread]

...

Currently the BrokerApiVersionsCommand tool uses its own custom admin client to send ApiVersions requests to broker. This is the last tool that relies on code from the old AdminClient.scala class. This tool is useful to identify what Kafka version a broker is running and which features it supports. For example, since 2.3, alterConfig has been deprecated and users should use incrementalAlterConfig instead. However there is no way to find if a broker supports this new API. Users have to attempt an incrementalAlterConfig call and if an UnsupportedOperationException is raised, fallback to alterConfig. Being able to get the supported ApiVersions per broker would simplify building robust client applications.

Public Interfaces

The plan is to expose 2 new methods in the org.apache.kafka.clients.admin.Admin interface:

default DescribeApiVersionsResultListApiVersionsResult describeApiVersionslistApiVersions(Collection<Node> brokers) {
    return describeApiVersionslistApiVersions(brokers, new DescribeApiVersionsOptionsListApiVersionsOptions());
}

DescribeApiVersionsResultListApiVersionsResult describeApiVersionslistApiVersions(Collection<Node> brokers, DescribeApiVersionsOptionsListApiVersionsOptions options);

With the following companion objects:
DescribeApiVersionsOptionsListApiVersionsOptions.java:

public class DescribeApiVersionsOptionsListApiVersionsOptions extends AbstractOptions<DescribeApiVersionsOptions>AbstractOptions<ListApiVersionsOptions> {
}

DescribeApiVersionsResultListApiVersionsResult.java:

public class DescribeApiVersionsResultListApiVersionsResult {

    public DescribeApiVersionsResultListApiVersionsResult(Map<Node, KafkaFutureImpl<NodeApiVersions>> futures) {}
    
    public Map<Node, KafkaFutureImpl<NodeApiVersions>> values() {}

    /**
     * Return a future which succeeds only if all the config descriptions succeed.
     */
    public KafkaFuture<Map<Node, KafkaFutureImpl<NodeApiVersions>>> all() {}
}

Move the existing NodeApiVersions internal class to a public package (org.apache.kafka.clients.admin) so it becomes per of the public API. This internal class is already exposed by BrokerApiVersionsCommand.

Proposed Changes

...

The proposal is to add support for retrieving the supported APIs in the AdminClient API. For that, the following changes are required:

• Add 2 new methods to the AdminClient API: listApiVersions(Collection) and listApiVersions(Collection, ListApiVersionsOptions)
  
• Add companion objects: ListApiVersionsOptions, ListApiVersionsResult
• Move existing NodeApiVersions class to org.apache.kafka.clients.admin
• Update BrokerApiVersionsCommand to use the new AdminClient methods

Compatibility, Deprecation, and Migration Plan

• What impact (if any) will there be on existing users?
• If we are changing behavior how will we phase out the older behavior?
• If we need special migration tools, describe them here.
• When will we remove the existing behavior?

Rejected Alternatives

• The BrokerApiVersionsCommand command line tool will keep working exactly as today
• No deprecation or migration plan required

Rejected Alternatives

If there are alternative ways of accomplishing the same thing, what were they? The purpose of this section is to motivate why the design is the way it is and not some other way.None