How to design an API: best practises, concepts, technical aspects

How to design an API: best practises, concepts, technical aspects

When I started to design Piwik I read a lot about APIs, software architecture, service oriented architecture (soa), etc. I really wanted to design a modular architecture that would make it easy to request any data and perform any action from outside the user interface.

Technically speaking, Piwik has been built on the top of Apis. Everything that does some logic in Piwik is available through an API. We basically open all these APIs via a REST API. Of course you must authenticate for some calls eg. when deleting a user. In ther user interface, the AJAX requests are directed to the API module that returns data in HTML or JSON format (javascript friendly).

Main concepts I tried to apply when designing the API:

• Easy to learn ; the documentation provides simple examples, complete documentation
• Easy to use ; single entry point, standard parameters
• Hard to misuse ; explicit error message suggesting parameters values
• Appropriate to audience ; I had chats about such a service with several phpmyvisites users, and I looked at what the competition was offering

Interesting resources that helped me have a better understanding of the topic:

• How to design a good API and why it matters? Great PDF presentation by a google engineer that I really enjoyed
• How to add an API to your webservice? Interesting read
• Audience drived based API design
• The art of building a reusable class library. A great presentation by a microsoft engineer ; be ready for the 237 slides!! (that’s a reason you end up working for microsoft when you like powerpoint so much!)

Of course to design a good API you should have a look at existing APIs, and even use some of them:

• A great example: Flickr API ; see an example of a method documentation ; try the API explorer for this method
• Mediawiki API
• A more complex example: Ebay API ; see an example of a method documentation (yes it’s impressive!!)
• A directory of existing APIs on programmable web
• Amazon API: example of the method ItemSearch
• And last but not least the Piwik API ; the best web analytics API that makes it easy to request anything from your best keywords, your top pages or the number of visits of the last 30 days, yesterday, or the previous 5 months. Give it a try.

If you have good resources or advice, feel free to post a comment