On this page you can view the list of APIs, how we maintain backwards compatibility, how we announce changes to the API and other useful tips.
Everything below is what we consider API.
index.php, URL structure ?module=API&method=X.Y&format=..., method names and parameter names are part of the API.piwik.php, parameter names are part of the API.@api in our sourcecode. (these docs are automatically generated on each commit.)core:archive, core:update, plugin:activate, plugin:deactivate, git:pull, development:enable, development:disable, customvariables:set-max-custom-variables.piwik.* object
config/global.ini.php are API
config/config.ini.phplibs/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 scriptpiwik.js is the minified JavaScript tracking client referenced in Tracking code in users' websites/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:
General_* and CoreHome_* keys, are part of the API and should not change.
Deprecations and changes to any of these public APIs will be documented here.
All popular software platforms have a process to ensure Backward Compatibility (BC) is kept between Minor and Patch releases (see Semantic Versioning 2.0.0). when BC is kept, it means users can be confident to upgrade to a newer version (Minor or Patch release) that their platform will still work (including any installed third party plugins.). For example Symfony have a very advanced BC guide: Our Backwards Compatibility Promise .
Rarely, we may have to break an API for example for security reasons. We mention any deprecations or breaking changes in our developer changelog see instructions.
When we need to change an API, or remove an API, before removing or changing the API, we deprecate it:
this can usually be done by adding @deprecated tag in the API, event name, etc.
we announce the deprecation in the Developer Changelog at least 3-6 months early. With the deprecated annotation we also mention when it was deprecated (which Matomo version) and provide recommendations what to use instead.
Example:
/**
* @deprecated since Matomo 4.2.1. Use Xyz instead.
*/
public function getMyReport() {
}
When we release a new Major version (eg. Matomo 5.0.0) then we are will remove all @deprecated code and therefore break BC. We announce the details of code removed in the developer changelog (see instructions) and we also document to developers how they can convert their code to the new way.
When we are adding a new API or when we are breaking or deprecating an existing API, then we change our Developer Changelog. We also mention library updates and on occasion internal changes that may be interesting for developers.
Any change would usually fall under one of these categories:
## Template: Matomo version number {#template-matomo-version-number}
### Breaking Changes {#breaking-changes}
### Deprecations {#deprecations}
### API Changes {#api-changes}
### New features {#new-features}
### New APIs {#new-apis}
### New commands {#new-commands}
### New config.ini.php settings {#new-configiniphp-settings}
### New developer guide {#new-developer-guide}
### Library updates {#library-updates}
### Internal change {#internal-change}
We provide a public PHP API for plugins so plugins can extend and customise Matomo. For example, they allow plugins to define new reports, widgets and track additional data. They also provide utility methods to store data, to show notifications, to define settings and more.
We aim to make as few classes as needed a public API, since they will be required to remain backwards compatible, while still providing plugin developers with a large enough stable API to effectively build with. Generally, to make a method or a class a public API the following criteria needs to be fulfilled:
$this->hourly('myTask'); to run an hourly task, but you can also use it in a very advanced way if needed (for example $this->custom($customSchedule, ...)).When making something a public API:
@api annotation in a comment or an entire class. When you mark an entire class as public API then all public methods and properties will become API automatically. Most of the time it is best to mark only the needed methods as API.This section applies to the HTTP API's that are defined in an API.php file within a plugin.
You can optionally add annotations to an API method to prevent a method to be visible in the list of all APIs. Please note that below annotations don't replace the need to check for the correct permissions in the beginning of the method.
@hide -> Won't be shown in list of all APIs but is also not possible to be called via HTTP API. It is not recommended to use this annotation and instead you should move this method to another place outside the API as there should be no reason to have it in the API if it's not supposed to be called.@hideForAll Same as @hide.@hideExceptForSuperUser Same as @hide but still shown and possible to be called by a user with super user access.@internal Won't be shown in list of all APIs but is possible to be called via HTTP API.Example:
/**
* @hideExceptForSuperUser
*/
public function getMyReport() {
}
We recommend avoiding using strong type in API request functions. If the inputs are not correct that could cause fatal errors when you expect regular error messages as a response
Avoid:
public function getExampleApi(?string $exampleParam)
{
}
Expected:
/**
* @param string|null $exampleParam
*/
public function getExampleApi($exampleParam)
{
}