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
