The best API's fit how users actually use them. I'm not sure there is a one-design-fits-all. One has to study to see what's done the most often and optimize around those, yet still allow flexibility for the times that deviate from common usage patterns. Make the common stuff short and easy, but the uncommon stuff possible and clear-cut. It may take a couple of iterations in actual use to tune it.<p>I also like "self-eating dogfood" in that the shortcuts are defined using existing "long-cuts" and the API user can study, learn from, and change and/or write their own shortcuts using the long-cuts.<p>C#'s optional-named-parameters (ONP) are ideal for such. I don't why Java and JavaScript don't implement ONP's. The alternatives, such as object literals and method overloading, are just too clunky. Once you tasted ONP's you don't wanna go back.