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 > > >
