Thanks for your feedback Ismael ! I was not aware of the InterfaceStability annotation ! I have updated the KIP based on your suggestions https://cwiki.apache.org/confluence/display/KAFKA/KIP-1265%3A+Mechanism+for+automatic+detection+of+internal+API+usage and hope that all your points have been added to it.
Team - Please do let me know your thoughts. Thanks, Ashwin On Tue, Jan 6, 2026 at 6:10 AM Ismael Juma <[email protected]> wrote: > 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 >> >
