When I started to design Matomo (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, Matomo has been built on the top of Apis. Everything that does some logic in Matomo 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!)

Updated September 2014 – six years after writing this article it is good to see how popular and useful APIs have become! Nowadays it’s all about RESTful Json APIs.

If you like watching videos this is a good one: REST+JSON API Design – Best Practices for Developers (video). We hope to release our JSON RESTful API for Matomo 3.0

End update

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!