The Matomo platform, our public APIs, and maintaining backward compatibility

[mattab]

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.

Up to date list of API's is now managed on our developer website. Please check there for an up to date list

https://developer.matomo.org/guides/apis

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
• Events
  • 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: core:archive, core:update, plugin:activate, plugin:deactivate, git:pull, development:enable, development:disable, customvariables:set-max-custom-variables.
  • some of these commands are setup in crontabs and we shouldn't break them.
• JavaScript variables in global piwik.* object
  • 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 config/config.ini.php
• 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
  • piwik.js is the minified JavaScript tracking client referenced in Tracking code in users' websites
  • alternatively /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 General_* and 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

[tsteur]

Closing this as it has not much value being open and rather is confusing looking at it repeatedly.

[tsteur]

this is now documented in https://developer.matomo.org/guides/apis