matomo-org · tsteur · Mar 17, 2021 · Mar 16, 2021 · Mar 16, 2021 · Mar 16, 2021
diff --git a/app/helpers/Content/Category/DevelopInDepthCategory.php b/app/helpers/Content/Category/DevelopInDepthCategory.php
@@ -30,6 +30,7 @@ public function getItems()
                 new Guide('pull-request-reviews'),
                 new Guide('core-team-workflow'),
                 new Guide('maintaining-plugins'),
+                new Guide('apis'),
                 new Guide('debugging-core'),
                 new Guide('profiling-code'),
                 new Guide('reproducing-issues'),

diff --git a/docs/4.x/apis.md b/docs/4.x/apis.md
@@ -1,70 +1,130 @@
 ---
 category: DevelopInDepth
 ---
-# Piwik APIs
+# Matomo APIs
 
-Piwik APIs serve two purposes: they serve the data used in controller methods, and they [automatically expose plugin functionality through an HTTP API](/guides/piwiks-reporting-api).
+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.
 
-In this guide, we discuss the first purpose.
+## List of APIs
 
-## About API Classes
+Everything below is what we consider API.
 
-Plugins provide APIs by defining a class named API that derives from [`Piwik\Plugins\API`](/api-reference/Piwik/Plugin/API). Every public method that does not have the `@ignore` annotation is exposed as part of Piwik's [Reporting HTTP API](/guides/piwiks-reporting-api).
+-   [Reporting HTTP API](/api-reference/reporting-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-reference/tracking-api)
+    -   API endpoint `piwik.php`, parameter names are part of the API.
+-   HTTP Status code for Reporting and Tracking APIs are API
+-   [Events](/api-reference/events)
+    -   Event names, and parameter list are API.
+-   [Classes](/api-reference/classes) and [Methods](/api-reference/index)
+    -   They are tagged with `@api` in our sourcecode. (these docs are automatically generated on each commit.)
+    -   Since PHP 8 argument names of public API's are also considered API
+-   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](https://developer.piwik.org/guides/working-with-piwiks-ui#global-variables-defined-by-piwik)
+-   LESS variables used for Theming
+    -   when [writing a theme for Piwik](/guides/theming) we announce that LESS variables in ([theme.less](https://github.com/piwik/piwik/blob/master/plugins/Morpheus/stylesheets/theme.less) and [theme-advanced.less](https://github.com/piwik/piwik/blob/master/plugins/Morpheus/stylesheets/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](http://piwik.org/docs/embed-piwik-report/) 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](https://piwik.org/docs/tracking-api/))
+    -   `misc/log-analytics/import_logs.py` <- [Log Analytics script](http://piwik.org/log-analytics/)
+    -   `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.
 
-All APIs are singletons. To access API methods programatically the [`getInstance()`](/api-reference/Piwik/Singleton#getinstance) method can be used:
+Some other parts are sometimes considered public APIs but it is not a hard rule:
 
-```php
-MyAPI::getInstance()->doSomething();
-```
-
-### API methods
+-   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.](/guides/translations#best-practices-for-new-translation-keys)
 
-API methods can take any number of parameters. Since they can be called through HTTP, methods must assume that parameters will be passed as strings. This also means that method parameters can only be simple values, such as `string`, `bool`, `numeric`, etc. or an array with simple values.
+Deprecations and changes to any of these public APIs will be documented here.
 
-API methods can return only one of four types of data:
+### Our Backwards Compatibility Promise
 
-- a simple value (`string`, `bool`, `numeric`, etc.)
-- a [DataTable](/api-reference/Piwik/DataTable) instance
-- a [DataTable\Map](/api-reference/Piwik/DataTable/Map) instance
-- an array of any of the values above
+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](http://semver.org/)). 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 ](http://symfony.com/doc/current/contributing/code/bc.html).
 
-This is so Piwik will always be able to convert the result into the desired output format in the reporting API.
+Rarely, we may have to break an API for example for security reasons. We mention any deprecations or breaking changes in our [developer changelog](/changelog) see [instructions](#developer-changelog).
 
-If an API method encounters an error, it should throw an exception. Piwik will be able to convert exceptions to the desired output format in the reporting API.
+### Deprecating a PHP or API method
 
-### API method security
+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.
 
-All API methods should check whether the current user is allowed to invoke the method. If the API method is read-only, this means checking that the user has view access to the resources the method returns. If the API method performs an action, this normally means checking that the user has either 'write' or 'admin' access to the functionality (or alternatively checking that the user is the super user). For example,
+Example:
 
 ```php
-public function getAllForSite($idSite)
-{
-    Piwik::checkUserHasViewAccess($idSite);
+/**
+ * @deprecated since Matomo 4.2.1. Use Xyz instead.
+ */
+public function getMyReport() {
 
-    return // ...
 }
 ```
 
-Look at the `check...` methods in the [Piwik](/api-reference/Piwik/Piwik) class to see what types of checks can be made. Or [learn more about permissions](https://developer.matomo.org/guides/permissions).
+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](/changelog) (see [instructions](#developer-changelog)) and we also document to developers how they can convert their code to the new way.
 
-### Calling API methods
+## Developer changelog
 
-API methods can be called in two ways. They can be called directly after getting the API singleton instance:
+When we are adding a new API or when we are breaking or deprecating an existing API, then we change our [Developer Changelog](https://github.com/matomo-org/matomo/blob/4.x-dev/CHANGELOG.md). We also mention library updates and on occasion internal changes that may be interesting for developers.
 
-```php
-MyAPI::getInstance()->doSomething(
-    Common::getRequestVar('idSite'),
-    Common::getRequestVar('date'),
-    Common::getRequestVar('period')
-);
-```
+### Examples when to update the developer changelog
 
-or they can be called using the [Piwik\API\Request](/api-reference/Piwik/API/Request) class:
+* change to a Reporting API method (eg. new API method added, deprecated, removed)
+* change to Reporting API output (eg. a new field in an API response)
+* change to Reporting API parameter (eg. parameter added, deprecated, removed)
+* change to Tracking API parameter (eg. parameter added, deprecated, removed)
+* change to Piwik JavaScript Tracker feature (eg. new feature, or removed feature)
+* since PHP 8 argument names of public API's are also considered API
+* new console command
+* new parameter for a console command
+* new developer guide
+* update to a third party library
+* any other relevant internal change that may interest developers
+
+Any change would usually fall under one of these categories:
 
-```php
-Request::processRequest("MyAPI.doSomething");
 ```
+#‎# Template: Matomo version number
+
+#‎## Breaking Changes
+#‎## Deprecations
+#‎## API Changes
+#‎## New features
+#‎## New APIs
+#‎## New commands
+#‎## New developer guide
+#‎## Library updates
+#‎## Internal change
+```
+
+If the change is a new config or a config change, then it's usually not mentioned in the developer changelog as they are mostly meant for users and not for developers.
 
-Note how in the second method, the [Common::getRequestVar](/api-reference/Piwik/Common#getrequestvar) method (which safely retrieves query parameter values) does not have to be called. The [Piwik\API\Request](/api-reference/Piwik/API/Request) class will forward the current request parameters to the API method which makes using it the better choice in some situations.
+## HTTP API
 
-Also note, that when [Piwik\API\Request](/api-reference/Piwik/API/Request) is used, [extra processing is applied to report data](/guides/piwiks-reporting-api#extra-report-processing).
+This section applies to the HTTP API's that are defined in an `API.php` file within a plugin.
+
+### Annotations
+
+You can optionally add annotations to an API method to prevent a method to be visible in the [list of all APIs](/api-reference/reporting-api). Please note that below annotations don't replace the need to [check for the correct permissions](/guides/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:
+
+```php
+/**
+ * @hideExceptForSuperUser
+ */
+public function getMyReport() {
+
+}
+```
diff --git a/docs/4.x/in-depth-reporting-api.md b/docs/4.x/in-depth-reporting-api.md
@@ -2,6 +2,5 @@
 category: Piwik In Depth
 title: Reporting API
 subGuides:
-  - apis
   - piwiks-reporting-api
 ---
diff --git a/docs/contributing-to-piwik-core.md b/docs/contributing-to-piwik-core.md
@@ -222,4 +222,4 @@ In most cases, it should be enough for your plugin to be available on the [Marke
 
 - learn **the basics of Piwik development** in [Getting started with plugins](/guides/getting-started-part-1).
 - to see a **list of available things you could work on**, see our [upcoming milestone](https://github.com/matomo-org/matomo/milestones)
-- learn **more about Matomo's tests** in our [Testing](/guides/tests) guide.
+- learn **more about Matomo's tests** in our [Testing](/guides/tests) guide.
diff --git a/docs/pull-request-reviews.md b/docs/pull-request-reviews.md
@@ -41,25 +41,7 @@ And if you are a core developer, if there is an issue that the pull request will
 
 ### Developer changelog
 
-When we are adding a new API method or when we are breaking or deprecating an existing API method, then we change our [Developer Changelog](https://github.com/matomo-org/matomo/blob/4.x-dev/CHANGELOG.md). We also mention library updates and on occassion internal changes that may be interesting for developers.
-
-Any change would usually fall under one of these categories:
-
-```
-## Template: Matomo version number
-
-### Breaking Changes
-### Deprecations
-### API Changes
-### New features
-### New APIs
-### New commands
-### Library updates
-### Internal change
-```
-
-If the change is a new config or a config change, then it's usually not mentioned in the developer changelog as they are mostly meant for users and not for developers.
-
+We keep the [developer changelog](/guides/apis#developer-changelog) up to date when any changes are made to what we [consider to be API](/guides/apis).
 
 ### Updating the pull request