Hi Ashwin, Improving how we specify public API and providing a mechanism for automatic detection of internal api usage would be great. That said, it's incorrect that there is no mechanism for that today. We should update the KIP to specify the current situation correctly and the problems with it.
A summary of items to consider for the KIP: 1. As a user, the way to know the public API is to consult the project's published javadoc: this is a "concrete, centralized definition of what constitutes a public API". 2. As a Kafka developer, you specify it via a block like this: https://github.com/apache/kafka/blob/trunk/build.gradle#L2026 3. There is no tooling that automatically detects if a public method exposes an internal class (there was a recent KIP that was introduced because we accidentally exposed an internal class) 4. There is no simple mechanism for users of Kafka to configure their build system so that usage of Kafka internal apis are flagged. 5. There are already annotations to specify whether a class or method is stable, evolving or unstable: https://github.com/apache/kafka/blob/trunk/clients/src/main/java/org/apache/kafka/common/annotation/InterfaceStability.java Thanks, Ismael On Sun, Jan 4, 2026 at 8:21 PM Ashwin via dev <[email protected]> wrote: > Hello folks, > > Reviving this old thread > https://lists.apache.org/thread/ly5ddkobr1wc07gvhwc1p0jg94qg8cxc to > discuss > KIP-1265. > > Apache Kafka lacks a concrete, centralized definition of what constitutes a > public API. The most relevant information currently available is found > here: > > Kafka Improvement Proposals#Whatisconsidereda%22majorchange%22thatneedsaKIP > < > https://cwiki.apache.org/confluence/display/KAFKA/Kafka+Improvement+Proposals#KafkaImprovementProposals-Whatisconsidereda%22majorchange%22thatneedsaKIP > > > > Without formal definition or guardrails, there is a risk that builders may > inadvertently import internal classes leading to possible build breakages > when they compile against a newer Kafka version > > > Please let me know your thoughts for > > https://cwiki.apache.org/confluence/display/KAFKA/KIP-1265%3A+Public+API+needs+to+be+explicitly+declared > > Cheers, > Ashwin >
