In this issue we shall describe what parts of the Piwik platform are publicly available for other developers to use. The goal of this issue ideally is to create a guide or page (likely on developer.piwik.org) to document this knowledge. ### Our public APIs
We call these "Public APIs" but this term can be a bit confusing as it includes more than just APIs.
Everything below is considered a public API:
- Reporting HTTP API.
- They are defined in API.php files and APIs are called over HTTP.
- API endpoint
index.php, URL structure
?module=API&method=X.Y&format=..., method names and parameter names are part of the API.
- Tracking HTTP API
- API endpoint
piwik.php, parameter names are part of the API.
- HTTP Status code for Reporting and Tracking APIs are API
- Event names, and parameter list are API.
- Classes and Methods
- They are tagged with
@api in our sourcecode. (these docs are automatically generated on each commit.)
- A few console commands are API (the command name and parameter names should not change)
- so far we only consider public APIs these commands:
- some of these commands are setup in crontabs and we shouldn't break them.
- as documented here
- LESS variables used for Theming
- when writing a theme for Piwik we announce that LESS variables in (theme.less and theme-advanced.less) are API
- INI Config settings names in
config/global.ini.php are API
- we should not rename INI config settings as users may have overridden them in
- Widgets embed URLs are API
- thousands of users include Piwik reports directly via the iframe embed feature and rely on the URL to work
- Some tools bundled with Piwik are considered API in the sense that their paths should not change:
libs/PiwikTracker/PiwikTracker.php <- tracker API client directly used from this path (as we advise in our doc)
misc/log-analytics/import_logs.py <- Log Analytics script
/js/ endpoint is sometimes used to serve the minified file ensuring caching of the file in browsers.
Some other parts are sometimes considered public APIs but it is not a hard rule:
- Translation keys, especially generic ones such as
CoreHome_* keys, are part of the API and should not change.
- Many plugins may use these generic translations, as we advise them to.
Deprecations and changes to any of these public APIs will be documented in the developer changelog #8127