January '08

19

Posted by

in About

Comments: 33 Comments

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:

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

If you have good resources or advice, feel free to post a comment. Good luck designing your API!

About author
piwik team member

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.

Like what you read?

Subscribe to our rss feed: Posts or you can Suggest a topic to write about in the blog or See list of Features

  1. tory burch Says:

    May 25, 2011 10:32 am

    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!

  2. Bauchladen Says:

    April 19, 2011 6:37 pm

    Is there a wordpress widget that integrates piwik?

  3. March 16, 2011 12:26 am

    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.

  4. Loan Guy Says:

    March 8, 2011 1:02 pm

    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!

  5. Entrümpeler Says:

    January 14, 2011 1:35 pm

    APIs have definitely become a great distribution channel and potentialy a new source of revenues.

  6. Dubai Says:

    December 18, 2010 10:53 am

    Great project with interesting good quality.

  7. Toronto Limo Says:

    December 15, 2010 4:32 pm

    Hey, great article.I stumbled this.

  8. December 11, 2010 4:27 pm

    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.

  9. December 8, 2010 2:54 pm

    Try yahoo auctions or even eBay

  10. December 7, 2010 1:04 pm

    Hey, great article.I spotted this while using bing on a semi related search. Reguards from England

  11. December 4, 2010 5:35 am

    I recognize piwik from something.

    Maybe my tracking software?

  12. December 4, 2010 5:00 am

    Wow, designing an API sounds intense.

    I don’t think I have the technical skills to pull that off. Very interesting though.

  13. using jquery Says:

    October 26, 2010 4:01 pm

    piwik is awesome

  14. October 7, 2010 8:27 am

    its really helpfull. i bookmarked it

  15. October 3, 2010 5:12 am

    this article is really very good and it is very useful. i think i am going to use some of these

  16. jon t Says:

    September 15, 2010 2:13 pm

    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.

  17. September 14, 2010 11:34 am

    An interesting and info post.

  18. Dave Says:

    July 14, 2010 10:19 pm

    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

  19. Maya Says:

    May 14, 2010 1:25 pm

    Awesome information!

  20. Angie Says:

    April 26, 2010 12:10 pm

    I will try now! :D

  21. Angie Says:

    April 26, 2010 12:09 pm

    That’s really cool Lara!! :)

  22. lara Says:

    April 13, 2010 7:43 pm

    Just designed my first API :)

  23. Sanya Says:

    April 5, 2010 12:00 am

    Interesting post! Thanx

  24. February 21, 2010 1:10 am

    This was a Excellent write up, have a awesome day.

  25. Pinoy Says:

    February 6, 2010 5:16 am

    This is indeed a helpful piece of article for our community. Hopefully, we can adopt it.

  26. January 6, 2010 8:56 pm

    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.

  27. January 6, 2010 8:54 pm

    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.

  28. sc-seo Says:

    September 30, 2009 3:17 am

    Ebay API , yes it’s impressive!! haha……

  29. July 26, 2009 8:03 pm

    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 :)

  30. July 22, 2009 10:15 am

    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.

  31. Sandy Saini Says:

    July 8, 2009 9:03 am

    I have been browsing throught your site. I find it very informative and very helpful.

    Great post!

Leave a Reply

Post Comment