@mattab opened this Issue on June 17th 2015 Owner

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
  • Events
    • Event names, and parameter list are API.
  • Classes and Methods
    • They are tagged with <a class='mention' href='https://github.com/api'>@api</a> 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
  • LESS variables used for Theming
  • 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
  • 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.

Deprecations and changes to any of these public APIs will be documented in the developer changelog #8127

Powered by GitHub Issue Mirror