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

[lachiebol]

Description

Also added legacy links to actual swagger pages. And changed OpenApiDocs to ApiReference

Checklist

• [✔] I have understood, reviewed, and tested all AI outputs before use
• [✔] All AI instructions respect security, IP, and privacy rules

Review

• Functional review done
• Potential edge cases thought about (behaviour of the code with strange input, with strange internal state or possible interactions with other Matomo subsystems)
• Usability review done (is anything maybe unclear or think about anything that would cause people to reach out to support)
• Security review done
• Wording review done
• Code review done
• Tests were added if useful/possible
• Reviewed for breaking changes
• Developer changelog updated if needed
• New documentation added or existing documentation updated

[lachiebol]

@AltamashShaikh We should merge when Cloud gets updated with new ApiReference

[AltamashShaikh]

@lachiebol Can you check this ?

High-Risk Issues Blocking

  - Legacy hash forwarding is incomplete for existing documented links. The redirect only maps window.location.hash when it exactly equals a generated
    pluginSpec.pluginName in app/templates/api-legacy-redirect.twig:12. Existing docs still contain links like /api-reference/reporting-api#TagManager, /api-
    reference/reporting-api#SitesManager, /api-reference/reporting-api#api-method-list, and /api-reference/reporting-api#optional-api-parameters. If the hash is not
    present in pluginSpecs, users are sent to the generic /api-reference/api index instead of either the matching new page or the preserved legacy anchor. This is
    especially visible because the branch text says “Old reporting API links now redirect here” in app/templates/api-swagger-index.twig:19, but many old links will
    not land on the intended content.

  Medium-Risk Issues

  - The redirect is client-side only. That is probably necessary for fragment-based redirects because URL hashes are not sent to the server, but non-JS users and
    crawlers only get the fallback content. The <noscript> meta refresh points to /api-reference/api and cannot preserve anchors in app/templates/api-legacy-
    redirect.twig:5.

[lachiebol]

@lachiebol Can you check this ?

High-Risk Issues Blocking

  - Legacy hash forwarding is incomplete for existing documented links. The redirect only maps window.location.hash when it exactly equals a generated
    pluginSpec.pluginName in app/templates/api-legacy-redirect.twig:12. Existing docs still contain links like /api-reference/reporting-api#TagManager, /api-
    reference/reporting-api#SitesManager, /api-reference/reporting-api#api-method-list, and /api-reference/reporting-api#optional-api-parameters. If the hash is not
    present in pluginSpecs, users are sent to the generic /api-reference/api index instead of either the matching new page or the preserved legacy anchor. This is
    especially visible because the branch text says “Old reporting API links now redirect here” in app/templates/api-swagger-index.twig:19, but many old links will
    not land on the intended content.

  Medium-Risk Issues

  - The redirect is client-side only. That is probably necessary for fragment-based redirects because URL hashes are not sent to the server, but non-JS users and
    crawlers only get the fallback content. The <noscript> meta refresh points to /api-reference/api and cannot preserve anchors in app/templates/api-legacy-
    redirect.twig:5.

@AltamashShaikh First one is a valid concern, fixed that one.

The second one should be fine, if someone is using no js it should probably just take them to the new page.

[AltamashShaikh]

@lachiebol It still says

This fixes only #api-method-list. Other existing legacy hashes like #optional-api-parameters, #TagManager, #SitesManager, #FormAnalytics, #HeatmapSessionRecording,
  #MediaAnalytics, and #CrashAnalytics still fall through to /api-reference/api#hash. In this checkout, the generated OpenAPI specs only include CustomTranslations,
  GithubAnalytics, LogViewer, LoginLdap, and TreemapVisualization, so most of those hashes will not map to a new plugin page.

The safer fix is to change the final fallback to:

  targetUrl = legacyUrl + '#' + hash;

[lachiebol]

@lachiebol It still says

This fixes only #api-method-list. Other existing legacy hashes like #optional-api-parameters, #TagManager, #SitesManager, #FormAnalytics, #HeatmapSessionRecording,
  #MediaAnalytics, and #CrashAnalytics still fall through to /api-reference/api#hash. In this checkout, the generated OpenAPI specs only include CustomTranslations,
  GithubAnalytics, LogViewer, LoginLdap, and TreemapVisualization, so most of those hashes will not map to a new plugin page.

The safer fix is to change the final fallback to:

  targetUrl = legacyUrl + '#' + hash;

It works, because all of the other hash params match sections in the current page.

Something like this should work
/api-reference/reporting-api#passing-an-array-of-data-as-a-parameter