One of the things we’re most excited about is giving developers APIs that they can use to do cool stuff with their music. Having an API is only half the battle though — having an API that’s awesome is more of a challenge but more rewarding too.

I’ve been on a mission to find a way to make sure our APIs are awesome and stay awesome. At the core I’ve come up with a set of principles that we’re going to try to follow. I based these on the work of a bunch of other folks like John Resig and Joshua Bloch.

• 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 document I’m working on goes into more detail on these principles and tries to capture some of the terminology, conventions and idioms of the two platforms we’re building APIs on top of - web page JavaScript and Mozilla. I would really appreciate feedback on this from a wide community.

Check it out: Songbird API Design Guidelines