Forward old API documentation url to new API documentation url, #PG-5032

app/helpers/OpenApiSpecRegistry.php

@@ -25,7 +25,7 @@ public static function getPluginMetadataPath()
     }
 
     /**
-     * @return array<int, array{name: string, slug: string, file: string, url: string, summary: string}>
+     * @return array<int, array{name: string, pluginName: string, slug: string, file: string, url: string, summary: string}>
      */
     public static function getPluginSpecs()
     {
@@ -50,6 +50,7 @@ public static function getPluginSpecs()
             $name = $matches[1];
             $specs[] = [
                 'name' => self::splitCamelCase($name),
+                'pluginName' => $name,
                 'slug' => self::toSlug($name),
                 'file' => $basename,
                 'url' => '/openapi/' . $basename,
@@ -66,7 +67,7 @@ public static function getPluginSpecs()
 
     /**
      * @param string $slug
-     * @return array{name: string, slug: string, file: string, url: string, summary: string}|null
+     * @return array{name: string, pluginName: string, slug: string, file: string, url: string, summary: string}|null
      */
     public static function getPluginSpecBySlug($slug)
     {
@@ -81,7 +82,7 @@ public static function getPluginSpecBySlug($slug)
 
     /**
      * @param string $slug
-     * @return array{pluginSpec: array{name: string, slug: string, file: string, url: string, summary: string}, pluginSpecData: array<mixed>}|null
+     * @return array{pluginSpec: array{name: string, pluginName: string, slug: string, file: string, url: string, summary: string}, pluginSpecData: array<mixed>}|null
      */
     public static function getPluginSpecDocumentBySlug($slug)
     {

app/helpers/Redirects.php

@@ -19,6 +19,8 @@ public static function getRedirects()
             '/api-reference/PHP-Piwik-Tracker/' => '/api-reference/PHP-Matomo-Tracker/',
             '/api-reference/php-piwik-tracker/' => '/api-reference/PHP-Matomo-Tracker/',
             '/api-reference/php-piwik-tracker' => '/api-reference/PHP-Matomo-Tracker/',
+            '/api-reference/reporting-api/' => '/api-reference/reporting-api',
+            '/api-reference/reporting-api-legacy/' => '/api-reference/reporting-api-legacy',
             '/contributing'                    => '/guides/contributing-to-piwik-core',
             '/plugins'                         => '/develop',
             '/core'                            => '/piwik-in-depth',

app/public/css/swagger-ui-overrides.css

@@ -203,3 +203,7 @@
     word-break: normal;
     word-wrap: normal;
 }
+
+#swagger-ui + .old-api-docs-paragraph {
+    margin-top: 18px;
+}

app/routes/page.php

@@ -119,6 +119,32 @@ function renderGuide(Slim\Views\Twig $view, Response $response, Psr\Http\Message
     ]);
 });
 
+$app->get('/api-reference/reporting-api', function (Request $request, Response $response, $args) {
+    $category = new ApiReferenceCategory();
+    $guide = new ApiReferenceGuide('api');
+
+    return $this->get("view")->render($response, 'api-legacy-redirect.twig', [
+        'category' => $category,
+        'guide' => $guide,
+        'linkToEditDocument' => $guide->linkToEdit(),
+        'activeMenu' => $category->getName(),
+        'currentPath' => $request->getUri()->getPath(),
+        'selectedPiwikVersion' => Environment::getPiwikVersion(),
+        'urlIfAvailableInNewerVersion' => (Environment::isLatestPiwikVersion() ? false : Url::getUrlIfDocumentIsAvailableInPiwikVersion($request->getUri()->getPath(), LATEST_PIWIK_DOCS_VERSION)),
+        'pluginSpecs' => OpenApiSpecRegistry::getPluginSpecs(),
+    ]);
+});
+
+$app->get('/api-reference/reporting-api-legacy', function (Request $request, Response $response, $args) {
+    return renderGuide(
+        $this->get("view"),
+        $response,
+        $request->getUri(),
+        new ApiReferenceGuide('reporting-api'),
+        new ApiReferenceCategory()
+    );
+});
+
 $app->get('/api-reference/api/{plugin}', function (Request $request, Response $response, $args) {
     $pluginSpecs = OpenApiSpecRegistry::getPluginSpecs();
     $pluginSpecDocument = OpenApiSpecRegistry::getPluginSpecDocumentBySlug($args['plugin']);

app/templates/api-legacy-redirect.twig

@@ -0,0 +1,38 @@
+{% extends 'guide.twig' %}
+
+{% set title = 'API Reference' %}
+
+{% block meta %}
+    <noscript>
+        <meta http-equiv="refresh" content="0;url={{ '/api-reference/api'|completeUrl }}">
+    </noscript>
+    <script type="text/javascript">
+        (function () {
+            let defaultUrl = '{{ '/api-reference/api'|completeUrl }}';
+            let legacyUrl = '{{ '/api-reference/reporting-api-legacy'|completeUrl }}';
+            let pluginSlugByLegacyHash = {
+{% for pluginSpec in pluginSpecs %}
+                '{{ pluginSpec.pluginName }}': '{{ pluginSpec.slug }}'{% if not loop.last %},{% endif %}
+{% endfor %}
+            };
+
+            let hash = window.location.hash.replace(/^#/, '');
+            let targetUrl = defaultUrl;
+
+            if (hash && pluginSlugByLegacyHash[hash]) {
+                targetUrl = '{{ '/api-reference/api/'|completeUrl }}' + pluginSlugByLegacyHash[hash];
+            } else if (hash === 'api-method-list') {
+                targetUrl = legacyUrl + '#' + hash;
+            } else if (hash) {
+                targetUrl = defaultUrl + '#' + hash;
+            }
+
+            window.location.replace(targetUrl);
+        })();
+    </script>
+{% endblock %}
+
+{% block guideContent %}
+    <p>Redirecting to the new API documentation.</p>
+    <p><a href="{{ '/api-reference/api'|completeUrl }}">Continue to the API reference</a></p>
+{% endblock %}

app/templates/api-swagger-index.twig

@@ -16,7 +16,7 @@
                 </li>
             {% endfor %}
         </ul>
-        <p class="old-api-docs-paragraph">Looking for the legacy API reference? The <a href="/api-reference/reporting-api">legacy API reference</a> page is still available while we continue improving the new API documentation. If anything is missing or behaving unexpectedly in this new version, <a href="https://matomo.org/support/">please let us know</a> so we can improve the experience.</p>
+        <p class="old-api-docs-paragraph"><em>Looking for the legacy API reference? The <a href="/api-reference/reporting-api-legacy">legacy API reference</a> page is still available. Old reporting API links now redirect here. If anything is missing or behaving unexpectedly in this new version, <a href="https://matomo.org/support/">please let us know</a> so we can improve the experience.</em></p>
     {% endif %}
 {% endblock %}
 

app/templates/api-swagger.twig

@@ -12,6 +12,7 @@
         Test API requests use our public demo environment. Because of this, read requests work but requests that create, edit, or delete data do not.
     </div>
     <div id="swagger-ui"></div>
+    <p class="old-api-docs-paragraph"><em>Looking for the legacy API reference? The <a href="{{ ('/api-reference/reporting-api-legacy'|completeUrl) ~ '#' ~ pluginSpec.pluginName }}">legacy API reference</a> page is still available. Old reporting API links now redirect here. If anything is missing or behaving unexpectedly in this new version, <a href="https://matomo.org/support/">please let us know</a> so we can improve the experience.</em></p>
 {% endblock %}
 
 {% block footer %}

fetch-openapi-specs.php

@@ -145,7 +145,7 @@ function fetchJson(string $baseUrl, string $tokenAuth, array $params): array
 
 try {
     $plugins = fetchJson($baseUrl, $tokenAuth, [
-        'method' => 'OpenApiDocs.getAllowedPlugins',
+        'method' => 'ApiReference.getAllowedPlugins',
     ]);
 } catch (Throwable $e) {
     fwrite(STDERR, "Failed to fetch plugin whitelist: {$e->getMessage()}\n");
@@ -154,7 +154,7 @@ function fetchJson(string $baseUrl, string $tokenAuth, array $params): array
 
 try {
     $pluginMetadata = fetchJson($baseUrl, $tokenAuth, [
-        'method' => 'OpenApiDocs.getAllowedPluginMetadata',
+        'method' => 'ApiReference.getAllowedPluginMetadata',
     ]);
 } catch (Throwable $e) {
     fwrite(STDERR, "Failed to fetch plugin metadata: {$e->getMessage()}\n");
@@ -181,7 +181,7 @@ function fetchJson(string $baseUrl, string $tokenAuth, array $params): array
 
     try {
         $spec = fetchJson($baseUrl, $tokenAuth, [
-            'method' => 'OpenApiDocs.getGeneratedOpenApiSpec',
+            'method' => 'ApiReference.getGeneratedOpenApiSpec',
             'plugin' => $plugin,
         ]);