How do you define a good or bad API? [closed]

Answer 1

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

Answer 2

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

Answer 3

I think a good API should allow custom IO and memory management hooks if it's applicable.

A typical example is you have your custom compressed archive format for data on disk and a third party library with a poor api wants to access data on disk and expects a path to a file where it can load its data.

This link has some good points: http://gamearchitect.net/2008/09/19/good-middleware/

Answer 4

• Useful - it addresses a need that is not already met (or improves on existing ones)
• Easy to explain - the basic understanding of what it does should be simple to grasp
• Follows some object model of some problem domain or real-world. It uses constructs that make sense
• Correct use of synchronous and asynchronous calls. (don't block for things that take time)
• Good default behavior - where possible allow extensibility and tweaking, but provide defaults for all that is necessary for simple cases
• Sample uses and working sample applications. This is probably most important of all.
• Excellent documentation
• Eat your own dog food (if applicable)
• Keep it small or segment it so that it is not one huge polluted space. Keep functionality sets distinct and isolated with few if any dependencies.

There are more, but that is a good start

Answer 5

A good API has a semantic model close to the thing it describes.

For example, an API for creating and manipulating Excel spreadsheets would have classes like Workbook, Sheet, and Cell, with methods like Cell.SetValue(text) and Workbook.listSheets().

Answer 6

You don't have to read the documentation to use it correctly.

The sign of an awesome API.