How to Design a Good API and Why it Matters

http://wenku.baidu.com/link?url=DNX_g0Q2q3oWM5PaAZUjUVQU09CigFjf9Qr87d1ZY2RhoEwNoUbzQ0OOYfgvlUFGBq_H0VRHBWcbW7ikzsPSTWwfZolFKXBMeIngv3Rv_Sq

Characteristics of a Good API
• Easy to learn
• Easy to use, even without documentation
• Hard to misuse
• Easy to read and maintain code that uses it
• Sufficiently powerful to satisfy requirements
• Easy to extend
• Appropriate to audience

API Should Do One Thing and Do it Well

Functionality should be easy to explain
_ If it's hard to name, that's generally a bad sign
_ Good names drive development
_ Be amenable to splitting and merging modules

API Should Be As Small As Possible But No Smaller

API should satisfy its requirements
• When in doubt leave it out
_ Functionality, classes, methods, parameters, etc.
_ You can always add, but you can never remove
• Conceptual weight more important than bulk
• Look for a good power-to-weight ratio

Implementation Should Not Impact API

Implementation details
_ Confuse users
_ Inhibit freedom to change implementation
• Be aware of what is an implementation detail
_ Do not overspecify the behavior of methods
_ For example: do not specify hash functions
_ All tuning parameters are suspect
• Don't let implementation details “leak” into API
_ On-disk and on-the-wire formats, exceptions

Minimize Accessibility of Everything

Make classes and members as private as possible
• Public classes should have no public fields
(with the exception of constants)
• This maximizes information hiding
• Allows modules to be used, understood, built,
tested, and debugged independently

Names Matter–API is a Little Language

Names Should Be Largely Self-Explanatory
_ Avoid cryptic abbreviations
• Be consistent–same word means same thing
_ Throughout API, (Across APIs on the platform)
• Be regular–strive for symmetry
• Code should read like prose