API Design

Recently at Songbird I've been working on some guidelines to help us build better APIs. One of the most exciting things we're hoping to offer users and developers are APIs that give them access to their music and the ability to extend their and others' music players. Getting these APIs right can be hard and we think we can do better, so we came up with some ideas and we're trying to get some wider feedback.

Our guidelines come in two parts - general rules that apply across the board, and platform-specific conventions depending on what the specific APIs are based on (Mozilla Extension API vs Web Page JavaScript). Here's our general guidelines:

• APIs should be orthogonal and symmetrical
• Method naming, argument ordering and error handling should be consistent
• Code that uses the API should read like prose. Words should not be abbreviated. It should be easy to understand code that uses the API without having read the documentation
• The API should follow the terminology, conventions and idioms of the platform that is is built on
• Use cases and target developers should be taken into consideration when the API is being designed and documented
• Developers should be able to continue to use the tools and libraries that they are familiar with when using the API. Their previous development experience should help them learn and understand the API quickly

The full document fleshes these out a little more, with examples and then goes into platform specific patterns to follow.

If you're interested, read it and please send your comments.