English
Software geeks: How Piwik automatically generates the API, using PHP Reflection
Friendly warning: blog post for software geeks only!
What is an “API” in Piwik and how to use it?
In Piwik, every plugin can expose its own API. Creating an API in a Piwik plugin is as easy as creating a class in a file called API.php; see example of the UserCountry/API.php API.
This class is then automatically loaded in Piwik and the public methods of the class are automatically available to call as a REST web service. For example, to call the method
public function getCountry( $idSite, $period, $date )
You can simply call:
index.php?module=API&method=UserCountry.getCountry&idSite=1&period=day&date=yesterday&format=xml&token_auth=X
You can see that the parameters idSite, date and period are automatically mapped from the URL to the original php function. This is where the magic happens, using the PHP Reflection API.
The page piwik/index.php?module=API&action=listAllAPI, available from the “API” link in the top bar of the Piwik user interface, will load all plugins API files, and automatically generate the “documentation”, with example links to the calls.
How is this automatic REST API implemented in PHP5?
I have published a quick presentation about the concept behind the implementation of this API code. Here is the embed presentation:
You can also see the presentation on slideshare: “Easy rest service using PHP reflection api – on slideshare”
All the code used for this API functionnality is located in piwik/core/API/* ; you can browse this code online in the Piwik code browser. Feel free to reuse this code in your project, and submit any patch that you may have to the Piwik team.
If you’re interested by this topic, see also the blog post: How to design an API?
Let us know your feedback or questions.
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
Tanya Says:
You ought to take part in a contest for one of the best sites online.
I most certainly will highly recommend this blog!
pandora Says:
hearing from webmasters that make use of Piwik simple reports and UI to analyze their websites and blogs, and optimize them to increase traffic and conversions.
patrik Says:
Hi, the API works great, can you show us some demo designs?
Ferienhaus Slowakei Says:
Danke aus der Slowakei für die Erklärungen
andrew Says:
@Rob agree with you, this is definitely not REST, but still a pretty awesome API automation. Also, SOAP is more evil than the combined denizens of the 7th layer of hell. Please never use SOAP, Piwik!
Dan Foley Says:
While I am weak on programming I appreciate your video about the API. Just wish I understood it better.
Andrew Gerber Says:
Being the owner of internet marketing company myself I find this article very interesting.
Arvind Says:
Hi,
Please provide me an good example to use this API on the Flash
Net Age Internet Marketing Says:
Hmmmm, I just did a post and it just disappeared, so lets try again.
I was commenting on the fact that Piwik is using the PHP reflection to auto-generate the API, and that I’m pleased to see a worthwhile alternative to Google Analytics. I expect to see some serious growth from Piwik and am definitely going to experiment with it myself.
Net Age Internet Marketing Says:
Piwik is impressing me no end, and the PHP Reflection API is a very effective way of getting the job done. Congratulations on a seriously good offering. May Piwik dominate the world of website analytics in the very near future. You’ve got my support, thats for sure!
halfdan Says:
Very cool! Has there been any thought of making Piwik available as php archive? (phar)
Yooer Says:
very gut community, tank you.
Katryn Says:
Классно!! А то блин везде все не то. Но тут нормально вышло
Christian Küpers Says:
That seems to become a very easy kind of implementation. Go on and it will get an very interesting solution as alternative to analytics.
frisbeeboomerang Says:
very gut community, tank you.