Krzysztof’s Laws of API Design

I always thought about writing down the laws of APIs design. By "laws", I mean principles that don’t seem to change based on the particular scenario at hand, whether the API is low of high level, etc. Here is my first try. I would appreciate any comments.

Update: "usability" in this context means "how easy to use the library is".

1. The usability of a namespace is inversely proportional to the number of public types in the namespace.
2. The usability of a type is inversely proportional to the number of public members of that type.
3. The usability of a member is inversely proportional to the number of parameters this member has.
4. The usability of a framework is inversely proportional to the sum of the number of explicit constructor invocations required and the number of types whose static methods need to be invoked to implement common scenarios.
5. The likelihood of an abstraction being designed correctly is inversely proportional to the number of abstract members on that abstraction.
6. The likelihood of an abstraction being designed correctly is proportional to the sum of the number of members taking it as a parameter and the number of types implementing it.
7. The likelihood of a virtual member being designed correctly is inversely proportional to the size of the member’s body.
8. The likelihood of a virtual member being designed correctly is proportional the sum of members calling it and the number of members overriding it.

Comments

• Anonymous
  December 20, 2005
  If I understood correctly, applying laws 1, 2 and 3, the best class library in the world has:
  one namespace
  with one type
  that has one member
  with one parameter.
  
  Or a member without parameters
  or no members
  or just an empty class library.
  
  Sorry, I couldn't resist :-)

• Anonymous
  December 20, 2005
  I think you are expressing a pretty cynical or jaded view of API design. The theme of these laws is "less is more" - but the tension is that at the same time we know that less is less. In other words, usability is a function of both learnability (less is more) and functionality (less is less, or more is more). Therefore, usability is probably more like a curve that starts at zero, climbs up as more stuff is added, but converges at some kind of maximum, or at a minimum, has diminishing marginal returns.

• Anonymous
  December 20, 2005
  These are fair comments; I should have clarified what I mean by "usability." When I say "usability," I mean "how easy to use the library is". Overall goodness (utility?) of a library is some combination of usability and functionality.

• Anonymous
  December 21, 2005
  In summary, write the least code that meets the requirements. If a package with no namespaces, no types, and no members works for the client, ship it!

• Anonymous
  December 26, 2005
  Note that KC focuses on API or publicly accessible parts (Type, Member, etc) of a framework or library. It doesn't deal much with the internal object model of the framework or library.
  
  Internally, the public Types or Members of a framework or library may delegates the works to other internal or private Types or Members; Adapter objects, Command Objects, Strategy Objects, etc... just like the long live OO design.

• Anonymous
  December 30, 2005
  I was wondering if you could recommend any additional reading material (online or offline)that goes into the details of good API design?
  
  I come from a web dev background and I'm moving more & more into the web services arena with C# so this sort of area is pretty new to me and I'd like to make sure my work is as clean as possible.
  
  Cheers.

• Anonymous
  July 13, 2006
  Here's one more collection of links.  It took me quite a while, and I threw out 90% of the links...

• Anonymous
  November 02, 2006
  WOW. This is so, so, so true, and succint and precise. I feel that every developer should take the "laws" print it out and stick it on a wall in front of her monitor. (I certainly did) Thanks Krzysztof!

• Anonymous
  October 08, 2008
  Krzysztof Cwalina's Laws of API Design...

• Anonymous
  August 05, 2009
  I'd like another one: The usability of an API is directly related to the quality of its documentation which is expressed in the length of sentences and the number of substantives per sentence. Err, I mean, write the documentation for programmers, not for lawyers.