Many times I struggled with API design dilemma which I didn't know how to solve perfectly. As all know, API design is important. However, it is difficult to get it right. Actually, nothing is absolutely right or wrong. What matters is tradeoff. I googled and found a pretty good article (written by Michi Henning from ZeroC) which give insight about API design. The article is here.
I agree with most of the author's viewpoints. Here I just would like to outline the elaborate article. Most following content is from the article. Gradually, I will add my own viewpoints and guidelines about how to design good API.
The effect of bad-designed API:
"Even minor and quite innocent design flaws have a tendency to get magnified out of all proportion because APIs are provided once, but are called many times. If a design flaw results in awkward or inefficient code, the resulting problems show up at every point the API is called. In addition, separate design flaws that in isolation are minor can interact with each other in surprisingly damaging ways and quickly lead to a huge amount of collateral damage.
The lower in the abstraction hierarchy an API defect occurs, the more serious are the consequences."
How to design good API:
"(1) APIs should be designed from the perspective of the caller.
APIs should be documented before they are implemented.
(2) An API must provide sufficient functionality for the caller to achieve its task.
(3) An API should be minimal, without imposing undue inconvenience on the caller.
(4) APIs cannot be designed without an understanding of their context.
(5) General-purpose APIs should be "policy-free;" special-purpose APIs should be "policy-rich."
(6) Good APIs don't pass the buck.
(7) Good APIs are ergonomic. "
Posts
