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 (10)

  1. 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 🙂

  2. tzagotta says:

    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.

  3. 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.

  4. Skip Sailors says:

    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!

  5. 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.

  6. Sam says:

    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.

  7. Here’s one more collection of links.  It took me quite a while, and I threw out 90% of the links…

  8. Rushabh says:

    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!

  9. Krzysztof Cwalina’s Laws of API Design…

  10. Robert says:

    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.

Skip to main content