How do you define a good or bad API? [closed]
Solution 1:
In API design I've always found this keynote very helpful:
How to Design a Good API and Why it Matters - by Joshua Bloch
Here's an excerpt, I'd recommend reading the whole thing / watching the video.
II. General Principles
- API Should Do One Thing and Do it Well
- API Should Be As Small As Possible But No Smaller
- Implementation Should Not Impact API
- Minimize Accessibility of Everything
- Names Matter–API is a Little Language
- Documentation Matters
- Document Religiously
- Consider Performance Consequences of API Design Decisions
- Effects of API Design Decisions on Performance are Real and Permanent
- API Must Coexist Peacefully with Platform
III. Class Design
- Minimize Mutability
- Subclass Only Where it Makes Sense
- Design and Document for Inheritance or Else Prohibit it
IV. Method Design
- Don't Make the Client Do Anything the Module Could Do
- Don't Violate the Principle of Least Astonishment
- Fail Fast - Report Errors as Soon as Possible After They Occur
- Provide Programmatic Access to All Data Available in String Form
- Overload With Care
- Use Appropriate Parameter and Return Types
- Use Consistent Parameter Ordering Across Methods
- Avoid Long Parameter Lists
- Avoid Return Values that Demand Exceptional Processing
Solution 2:
You don't have to read the documentation to use it correctly.
The sign of an awesome API.
Solution 3:
Many coding standards and longer documents and even books (Framework Design Guidelines) have been written on this topic, but much of this only helps at a fairly low level.
There is also a matter of taste. APIs may obey every rule in whatever rulebook, and still suck, due to slavish adherence to various in-vogue ideologies. A recent culprit is pattern-orientation, wherein Singleton Patterns (little more than initialized global variables) and Factory Patterns (a way of parameterizing construction, but often implemented when not needed) are overused. Lately, it's more likely that Inversion of Control (IoC) and associated explosion in the number of tiny interface types that adds redundant conceptual complexity to designs.
The best tutors for taste are imitation (reading lots of code and APIs, finding out what works and doesn't work), experience (making mistakes and learning from it) and thinking (don't just do what's fashionable for its own sake, think before you act).