English
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 the user interface, AJAX requests are directed to the API module that returns data in HTML or JSON format (javascript friendly).
Here are the 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 talked about such a service with several users, and 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 take 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 with this tutorial.
If you have good resources or advice, feel free to post a comment. Good luck designing your API!
Matthieu Aubry
While studying in India in 2006, Matthieu had the idea of creating an open source web analytics alternative to Google Analytics. In 2007 he released the first public beta version of Piwik. Matthieu now leads the project from New Zealand, where he likes to spend his days coding new features from the Piwik Roadmap, and helping users and customers use Piwik effectively. Find him on twitter or github.
Subscribe to our rss feed: 
Posts or you can Suggest a topic to write about in the blog or See list of Features
tory burch Says:
I just started using Piwik as an alternative to analytics but to be honest I am struggling to understand how the API stuff can be used!
Bauchladen Says:
Is there a wordpress widget that integrates piwik?
Online Scratch Cards Says:
The rise of social gaming over the past several years has been amazing to watch. There was truly a perfect storm of events which catapulted social games into the top level of gaming. Everything from the popularity of facebook to the addictive nature of the games played their part.
Loan Guy Says:
I just started using Piwik as an alternative to analytics but to be honest I am struggling to understand how the API stuff can be used!
Entrümpeler Says:
APIs have definitely become a great distribution channel and potentialy a new source of revenues.
Dubai Says:
Great project with interesting good quality.
Toronto Limo Says:
Hey, great article.I stumbled this.
seo @ consultant seek Says:
This seems that API’s really going for the new revenues online but they have a strong background for their new clients , but i didn’t get the source pages given in the blogs , why they are here, actually . I think they are just for easy processing.
Buy Textbooks Online Cheap Says:
Try yahoo auctions or even eBay
Issac Siddall Says:
Hey, great article.I spotted this while using bing on a semi related search. Reguards from England
Azoogle Review Says:
I recognize piwik from something.
Maybe my tracking software?
AdSense Revenue Sharing Blog Says:
Wow, designing an API sounds intense.
I don’t think I have the technical skills to pull that off. Very interesting though.
using jquery Says:
piwik is awesome
sonic alarm clock Says:
its really helpfull. i bookmarked it
spiderman games Says:
this article is really very good and it is very useful. i think i am going to use some of these
jon t Says:
Your post is quite informative. I am a layman and found your links to how to add an API to your webservice and your closing links about trying the analytic tool most beneficial. I am in the process of having a couple of websites built and will forward the link to my developer.
Sandra Shirtman Says:
An interesting and info post.
Dave Says:
Good Tutorial, took 20 mins to read about but is surely gonna help me.APIs have definitely become a great distribution channel and potentialy a new source of revenues.Regards, Dave from VoIP Guide
Maya Says:
Awesome information!
Angie Says:
I will try now! :D
Angie Says:
That’s really cool Lara!! :)
lara Says:
Just designed my first API :)
Sanya Says:
Interesting post! Thanx
increase free testosterone Says:
This was a Excellent write up, have a awesome day.
Pinoy Says:
This is indeed a helpful piece of article for our community. Hopefully, we can adopt it.
watch alice in wonderland online Says:
I have just come across this site and have so far found it very interesting and informative. I had absolutely no idea about how much actually goes into web design, all we can do is learn learn and see how one goes.
watch alice in wonderland online Says:
The application programming interface is of paramount importance if you desire to tweak or program, and this article is useful in helping one determine an effective baseline. Some of the links are downright handy too, and I thoroughly enjoyed the little dig at Microsoft and their Powerpoint crazy engineer. It is worth sitting throught the slideshow though.
sc-seo Says:
Ebay API , yes it’s impressive!! haha……
Adirec Torytski Says:
there’s sooooooooo much to learn about web design … API’s ??? I’ve read some about it, but no idea how they work … I need a second brain :)
Jacques | Web Design Says:
The application programming interface is of paramount importance if you desire to tweak or program, and this article is useful in helping one determine an effective baseline. Some of the links are downright handy too, and I thoroughly enjoyed the little dig at Microsoft and their Powerpoint crazy engineer. It is worth sitting throught the slideshow though.
Sandy Saini Says:
I have been browsing throught your site. I find it very informative and very helpful.
Great post!