Recommendations for writing an API

Question

I'm about to write an api and thought I'd find some good recommendations on things to look out for, how to write a good api.

I of course did a google search, but aside from this from Dustin Diaz http://www.dustindiaz.com/api-writing-tips/, I haven't really been able to find good recommendations.

What are things that you wish you had done differently when creating an API? What made the biggest difference.

I assuming I'm going to use oauth.

I'm purposely not providing details of the api, as I'm looking for more general recommendations that will hopefully be useful to a larger number of people.

Answer 1

Key points I would recommend you look at:

• Implement a RESTful interface
• Offer a variety of data formats (JSON, XML, etc)
• Make the syntax intuitive and easy to understand
• Thorough documentation
• Use proper response codes

Also, here are some links you may find useful:

http://www.slideshare.net/eaton/building-apis-that-rock
http://www.notiondesign.ca/blog/story/how-not-to-build-an-api/
http://blog.apigee.com/category/api_best_practices/
http://blog.isnotworking.com/2007/05/api-design-guidelines.html

Also, this is a great book that may help you get started:

http://www.amazon.com/dp/0596529260/