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.
Published 20 December 05 11:48 by kcwalina
Filed under:

Comment Notification

If you would like to receive an email when updates are made to this post, please register here

Subscribe to this post's comments using RSS

Comments

# Diego Mijelshon said on December 20, 2005 3:11 PM:
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 :-)
# tzagotta said on December 20, 2005 3:57 PM:
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.
# kcwalina said on December 20, 2005 6:23 PM:
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.
# Skip Sailors said on December 21, 2005 11:19 AM:
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!
# Norman Sasono said on December 26, 2005 7:41 PM:
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.
# Sam said on December 30, 2005 11:28 AM:
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.
# Life, Universe and Everything according to Dirk said on July 14, 2006 1:30 AM:
Here's one more collection of links.  It took me quite a while, and I threw out 90% of the links...
# Rushabh said on November 2, 2006 3:12 PM:

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!

# IWebThereforeIAm said on October 8, 2008 10:41 PM:

Krzysztof Cwalina's Laws of API Design...

Leave a Comment

(required) 
(optional)
(required) 
Page view tracker