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 >
