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