Hello all, I have created a KIP discussion thread here https://lists.apache.org/thread/0lptz5bm4nxsynk2d6vjwmjdn77d2o5w. Let's continue our discussion there.
Thanks, Ashwin On Thu, Dec 18, 2025 at 9:45 AM Ashwin <[email protected]> wrote: > Hi Josep and Christopher, > > Thanks for the feedback. > > Josep, I agree with the idea of adding annotations. I was initially > considering a model similar to Hadoop’s Interface Classification ( > https://hadoop.apache.org/docs/stable/hadoop-project-dist/hadoop-common/InterfaceClassification.html), > which uses two annotations to track audience and stability. However, that > may be over-complicated. I prefer your simpler suggestion: anything not > marked as Public or ApiMayChange can be assumed to be private. > > Christopher, thank you for sharing the information about APILyzer. We > could use a similar approach, as shown in this annotation example ( > https://code.revelc.net/apilyzer-maven-plugin/#annotation-example), to > ensure that public APIs only import other public APIs. > > There is another dimension to this regarding plugin development (e.g., > connector implementations). I’ve frequently seen internal classes used in > these projects, especially within tests. To prevent the unintentional use > of internal APIs, we could either: > > a. Suggest an APILyzer-like configuration for plugin builds. > b. Use Java 9+ modules to export only public classes. > > Option A is easier to implement but relies on developer awareness. Option > B is more complex but provides a definitive way to prevent external > projects from using internal classes. > > Please let me know your thoughts. > > Cheers, > Ashwin > > On Thu, Dec 18, 2025 at 1:39 AM Christopher Shannon < > [email protected]> wrote: > >> Apache Accumulo uses the APILyzer maven plugin for this purpose and it >> works pretty well at preventing internal types from leaking into the >> defined public API. >> >> https://github.com/revelc/apilyzer-maven-plugin >> https://code.revelc.net/apilyzer-maven-plugin/ >> >> I haven't found a similar Gradle plugin, but the plugin is Apache 2 >> licensed and the core logic could probably be extracted and adapted into a >> Gradle plugin. >> >> On Wed, Dec 17, 2025 at 4:29 AM Josep Prat via dev <[email protected]> >> wrote: >> >> > I also thought about this particular problem some time ago and I was >> > thinking of proposing something similar as what Pekko does. >> > Pekko has 4 types of annotations that identify intent on what they class >> > can be used for: >> > - Internal and might change the API without further notice: >> > >> > >> https://github.com/apache/pekko/blob/main/actor/src/main/java/org/apache/pekko/annotation/InternalApi.java >> > - Internal but other internal modules depend on it, so the API should be >> > quite stable: >> > >> > >> https://github.com/apache/pekko/blob/main/actor/src/main/java/org/apache/pekko/annotation/InternalStableApi.java >> > - Do not inherit outside of the project: >> > >> > >> https://github.com/apache/pekko/blob/main/actor/src/main/java/org/apache/pekko/annotation/DoNotInherit.java >> > - Public API but still experimenting with it, so the API might still >> > change: >> > >> > >> https://github.com/apache/pekko/blob/main/actor/src/main/java/org/apache/pekko/annotation/ApiMayChange.java >> > >> > I believe Apache Kafka would benefit from: ApiMayChange (for features >> that >> > are in preview mode), and InternalApi (or PublicApi for that matter, >> > whatever is easier). >> > >> > >> > What are your thougths? >> > >> > Best, >> > >> > On Wed, Dec 17, 2025 at 10:21 AM Josep Prat <[email protected]> >> wrote: >> > >> > > One of the first definitions I was told by committers when I joined >> the >> > > project was that public API is anything that has a JavaDoc published. >> > > >> > > I do agree however, that we could do a better job at marking public >> APIs >> > > or marking non-public ones (whatever is easier). >> > > >> > > Best, >> > > >> > > On Wed, Dec 17, 2025 at 10:07 AM Ashwin via dev <[email protected] >> > >> > > wrote: >> > > >> > >> Hello Team, >> > >> >> > >> While reviewing discussions regarding public APIs in Kafka, I noticed >> > that >> > >> we lack a concrete, centralized definition of what constitutes a >> public >> > >> API. The most relevant information currently available is found here: >> > >> >> > >> >> > >> https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=50859233#KafkaImprovementProposals-Whatisconsidereda%22majorchange%22thatneedsaKIP >> > >> ( >> > >> >> > >> >> > >> https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=50859233#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. I believe we should >> > >> address this to ensure better consistency and prevent such >> occurrences. >> > >> >> > >> Please let me know if you feel this is something that can benefit the >> > >> community, I can present the possible approaches through a KIP. >> > >> >> > >> >> > >> Cheers, >> > >> Ashwin >> > >> >> > > >> > > >> > > -- >> > > [image: Aiven] <https://www.aiven.io> >> > > >> > > *Josep Prat* >> > > Sr. Engineering Director, Streaming Services, *Aiven* >> > > [email protected] | +491715557497 >> > > aiven.io <https://www.aiven.io> | >> > > <https://www.facebook.com/aivencloud> >> > > <https://www.linkedin.com/company/aiven/> < >> > https://twitter.com/aiven_io> >> > > *Aiven Deutschland GmbH* >> > > Alexanderufer 3-7, 10117 Berlin >> > > >> > > Geschäftsführer: Oskari Saarenmaa, Hannu Valtonen, >> > > >> > > Kenneth Chen >> > > Amtsgericht Charlottenburg, HRB 209739 B >> > > >> > >> > >> > -- >> > [image: Aiven] <https://www.aiven.io> >> > >> > *Josep Prat* >> > Sr. Engineering Director, Streaming Services, *Aiven* >> > [email protected] | +491715557497 >> > aiven.io <https://www.aiven.io> | < >> https://www.facebook.com/aivencloud >> > > >> > <https://www.linkedin.com/company/aiven/> < >> > https://twitter.com/aiven_io> >> > *Aiven Deutschland GmbH* >> > Alexanderufer 3-7, 10117 Berlin >> > >> > Geschäftsführer: Oskari Saarenmaa, Hannu Valtonen, >> > >> > Kenneth Chen >> > Amtsgericht Charlottenburg, HRB 209739 B >> > >> >
