Ismael raised the concern (offline) that even if we mark the API as unstable, people will use it right away because it is so valuable. So we'll have trouble changing later if we prefer a different API.
I agree, but since I still prefer to experiment a bit "in the wild", I suggested placing the AdminClient in its own Maven package (separate from kafka-clients). This will allow users to upgrade their AdminClient dependency when they want to, without worrying about being stuck with an older producer/consumer version at the same time. It should give us better ability to experiment since users can stay on the older APIs as long as they want. IMO, we can leave the packages separate forever and avoid pains of merging them. Does anyone see downsides to separate packages? On Tue, Feb 7, 2017 at 4:17 PM, Gwen Shapira <g...@confluent.io> wrote: >>> - Personally I don't think splitting the admin methods up actually makes >>> things more usable. It just makes you have to dig through our >>> hierarchy. I >>> think a flat class with a bunch of operations (like the consumer api) is >>> probably the easiest for people to grok and find things on. I am kind >>> of a >>> dumb PHP programmer at heart, though. >>> >> >> I am not sure it's fair to compare the AdminClient with the Consumer. The >> former has APIs for a bunch of unrelated APIs (topics, ACLs, configs, >> consumer groups, delegation tokens, preferred leader election, partition >> reassignment, etc.) where the latter is pretty specialised. For each of the >> resources, you may have 3-4 operations, it will get confusing fast. Also, >> do you really think an API that has one level of grouping will mean that >> users have to "dig through our hierarchy"? Or are you concerned that once >> we go in that direction, there is a danger of making the hierarchy more >> complicated? >> >> Finally, I am not sure I would use the consumer as an example of something >> that is easy to grok. :) The fact that methods behave pretty differently >> (some are blocking while others only have an effect after poll) with no >> indication from the type signature or naming convention makes it harder, >> not easier, to understand. > > > I also wouldn't consider the consumer a shining example of usability. > > Streams went in the "split stuff" direction. At the upper level, you > can either create a Stream or a Table. Then you have relevant methods > under each. They even have a bit more hierarchy: GroupedStream under > stream where aggregates live. I thought it works rather well once you > figure out the rules. > > But I think there is a class of engineers who learn how to use a > client by creating an instance in IntelliJ and then browse through the > list of methods available and see what looks right. Hierarchies throw > us off a bit off. I remember browsing KStream and freaking out because > I can't find "aggregate" method. So we need to make sure this thing > makes sense to new users (we can find a few to test on?). > > Since moving stuff around a hierarchy is fairly easy, why not try one > way, leave things as "unstable" for one release and gather feedback? > We usually get usability complaints fairly fast. > >> >> Ismael > > > > -- > Gwen Shapira > Product Manager | Confluent > 650.450.2760 | @gwenshap > Follow us: Twitter | blog -- Gwen Shapira Product Manager | Confluent 650.450.2760 | @gwenshap Follow us: Twitter | blog
