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!


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.