fix(api): links and headings in local API refs.

- Fix broken links reported by the e2e link checker.
- Add an e2e test for checking internal and external links in API reference docs. Low effort, big win.

Author: jstirnaman

api-docs/README.md

@@ -237,7 +237,7 @@ InfluxDB Cloud releases are frequent and not versioned, so the Cloud API spec is
 We regenerate API reference docs from `influxdata/openapi`
 **master** branch as features are released.
 
-### InfluxDB OSS version
+### InfluxDB OSS v2 version
 
  Given that
  `influxdata/openapi` **master** may contain OSS spec changes not implemented

api-docs/influxdb/cloud/v2/ref.yml

@@ -2143,7 +2143,6 @@ x-tagGroups:
       - Headers
       - Pagination
       - Response codes
-      - System information endpoints
   - name: All endpoints
     tags:
       - Ping

api-docs/influxdb/v2/v2/ref.yml

@@ -126,8 +126,8 @@ tags:
       |:------------------------ |:--------------------- |:-------------------------------------------|
       | `bucket`                 | string                | The bucket name or ID ([find your bucket](/influxdb3/cloud-serverless/admin/buckets/view-buckets/). |
       | `bucketID`               | string                | The bucket ID ([find your bucket](/influxdb3/cloud-serverless/admin/buckets/view-buckets/). |
-      | `org`                    | string                | The organization name or ID ([find your organization](/influxdb3/cloud-serverless/organizations/view-orgs/). |
-      | `orgID`                  | 16-byte string        | The organization ID ([find your organization](/influxdb3/cloud-serverless/organizations/view-orgs/). |
+      | `org`                    | string                | The organization name or ID ([find your organization](/influxdb3/cloud-serverless/admin/organizations/view-orgs/). |
+      | `orgID`                  | 16-byte string        | The organization ID ([find your organization](/influxdb3/cloud-serverless/admin/organizations/view-orgs/). |
     name: Common parameters
     x-traitTag: true
   - name: Config
@@ -443,11 +443,6 @@ paths:
             Specifies an authorization by its `token` property value
             and returns the authorization.
 
-            #### InfluxDB OSS
-
-            - Doesn't support this parameter. InfluxDB OSS ignores the `token=` parameter,
-              applies other parameters, and then returns the result.
-
             #### Limitations
 
             - The parameter is non-repeatable. If you specify more than one,
@@ -469,13 +464,6 @@ paths:
             If the response body is missing authorizations that you expect, check that the API
             token used in the request has `read-user` permission for the users (`userID` property value)
             in those authorizations.
-
-            #### InfluxDB OSS
-
-            - **Warning**: The response body contains authorizations with their
-              [API token](/influxdb3/cloud-serverless/reference/glossary/#token) values in clear text.
-            - If the request uses an  _[operator token](/influxdb/latest/security/tokens/#operator-token)_,
-              InfluxDB OSS returns authorizations for all organizations in the instance.
         '400':
           $ref: '#/components/responses/GeneralServerError'
           description: Invalid request
@@ -625,14 +613,6 @@ paths:
 
         Use this endpoint to retrieve information about an API token, including
         the token's permissions and the user that the token is scoped to.
-
-        #### InfluxDB OSS
-
-        - InfluxDB OSS returns
-          [API token](/influxdb3/cloud-serverless/reference/glossary/#token) values in authorizations.
-        - If the request uses an _[operator token](/influxdb/latest/security/tokens/#operator-token)_,
-          InfluxDB OSS returns authorizations for all organizations in the instance.
-
         #### Related guides
 
         - [View tokens](/influxdb3/cloud-serverless/security/tokens/view-tokens/)
@@ -740,14 +720,6 @@ paths:
         If no query parameters are passed, InfluxDB returns all buckets up to the
         default `limit`.
 
-        #### InfluxDB OSS
-
-        - If you use an _[operator token](/influxdb3/cloud-serverless/security/tokens/#operator-token)_
-          to authenticate your request, InfluxDB retrieves resources for _all
-          organizations_ in the instance.
-          To retrieve resources for only a specific organization, use the
-          `org` parameter or the `orgID` parameter to specify the organization.
-
         #### Required permissions
 
         | Action                    | Permission required |
@@ -863,13 +835,6 @@ paths:
         [retention period](/influxdb3/cloud-serverless/reference/glossary/#retention-period)
         is 30 days.
 
-        #### InfluxDB OSS
-
-        - A single InfluxDB OSS instance supports active writes or queries for
-        approximately 20 buckets across all organizations at a given time.
-        Reading or writing to more than 20 buckets at a time can adversely affect
-        performance.
-
         #### Limitations
 
         - InfluxDB Cloud Free Plan allows users to create up to two buckets.
@@ -2855,10 +2820,6 @@ paths:
           description: |
             Bad request.
             The response body contains detail about the error.
-
-            #### InfluxDB OSS
-
-            - Returns this error if the `org` parameter or `orgID` parameter doesn't match an organization.
         '401':
           $ref: '#/components/responses/AuthorizationError'
         '404':
@@ -2910,7 +2871,7 @@ paths:
 
         #### Related guides
 
-        - [View organizations](/influxdb3/cloud-serverless/organizations/view-orgs/)
+        - [View organizations](/influxdb3/cloud-serverless/admin/organizations/view-orgs/)
       operationId: GetOrgs
       parameters:
         - $ref: '#/components/parameters/TraceSpan'
@@ -3075,11 +3036,6 @@ paths:
           2. Returns an HTTP `204` status code if queued; _error_ otherwise.
           3. Handles the delete asynchronously.
 
-        #### InfluxDB OSS
-
-        - Validates the request, handles the delete synchronously,
-        and then responds with success or failure.
-
         #### Limitations
 
         - Only one organization can be deleted per request.
@@ -3104,9 +3060,6 @@ paths:
 
             #### InfluxDB Cloud
               - The organization is queued for deletion.
-
-            #### InfluxDB OSS
-              - The organization is deleted.
         '400':
           $ref: '#/components/responses/BadRequestError'
         '401':
@@ -3145,7 +3098,7 @@ paths:
 
         #### Related guides
 
-        - [View organizations](/influxdb3/cloud-serverless/organizations/view-orgs/)
+        - [View organizations](/influxdb3/cloud-serverless/admin/organizations/view-orgs/)
       operationId: GetOrgsID
       parameters:
         - $ref: '#/components/parameters/TraceSpan'
@@ -3909,10 +3862,6 @@ paths:
           description: |
             Bad request.
             The response body contains detail about the error.
-
-            #### InfluxDB OSS
-
-            - Returns this error if the `org` parameter or `orgID` parameter doesn't match an organization.
         '401':
           $ref: '#/components/responses/AuthorizationError'
         '404':
@@ -4894,10 +4843,6 @@ paths:
           description: |
             Bad request.
             The response body contains detail about the error.
-
-            #### InfluxDB OSS
-
-            - Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter.
         '401':
           $ref: '#/components/responses/AuthorizationError'
         '500':
@@ -6234,10 +6179,6 @@ paths:
             #### InfluxDB Cloud
 
               - Always returns this error; doesn't support cancelling tasks.
-
-            #### InfluxDB OSS
-
-              - Doesn't return this error.
         '500':
           $ref: '#/components/responses/InternalServerError'
         default:
@@ -8233,10 +8174,6 @@ components:
       description: |
         Bad request.
         The response body contains detail about the error.
-
-        #### InfluxDB OSS
-
-        - Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter.
     GeneralServerError:
       content:
         application/json:
@@ -11681,10 +11618,6 @@ components:
 
             - Doesn't use `shardGroupDurationsSeconds`.
 
-            #### InfluxDB OSS
-
-            - Default value depends on the [bucket retention period](/influxdb3/cloud-serverless/reference/internals/shards/#shard-group-duration).
-
             #### Related guides
 
             - InfluxDB [shards and shard groups](/influxdb3/cloud-serverless/reference/internals/shards/)
@@ -12132,10 +12065,6 @@ components:
         #### InfluxDB 3 Cloud Serverless
 
         - `retentionRules` is required.
-
-        #### InfluxDB OSS
-
-        - `retentionRules` isn't required.
       items:
         $ref: '#/components/schemas/RetentionRule'
       type: array
@@ -13400,7 +13329,7 @@ components:
             The organization owns all resources created by the template.
 
             To find your organization, see how to
-            [view organizations](/influxdb3/cloud-serverless/organizations/view-orgs/).
+            [view organizations](/influxdb3/cloud-serverless/admin/organizations/view-orgs/).
           type: string
         remotes:
           description: |
@@ -14817,9 +14746,6 @@ x-tagGroups:
       - Headers
       - Pagination
       - Response codes
-      - Data I/O endpoints
-      - Security and access endpoints
-      - System information endpoints
   - name: All endpoints
     tags:
       - Authorizations (API tokens)

api-docs/influxdb3/cloud-dedicated/v2/ref.yml

@@ -417,16 +417,6 @@ paths:
         '429':
           description: |
             Too many requests.
-
-            #### InfluxDB Cloud
-
-              - Returns this error if a **read** or **write** request exceeds your plan's [adjustable service quotas](/influxdb3/clustered/account-management/limits/#adjustable-service-quotas)
-                or if a **delete** request exceeds the maximum [global limit](/influxdb3/clustered/account-management/limits/#global-limits).
-              - For rate limits that reset automatically, returns a `Retry-After` header that describes when to try the write again.
-              - For limits that can't reset (for example, **cardinality limit**), doesn't return a `Retry-After` header.
-
-              Rates (data-in (writes), queries (reads), and deletes) accrue within a fixed five-minute window.
-              Once a rate limit is exceeded, InfluxDB returns an error response until the current five-minute window resets.
           headers:
             Retry-After:
               description: Non-negative decimal integer indicating seconds to wait before retrying the request.
@@ -578,12 +568,7 @@ paths:
                 type: string
         '429':
           description: |
-            #### InfluxDB Cloud:
-              - returns this error if a **read** or **write** request exceeds your
-                plan's [adjustable service quotas](/influxdb3/clustered/account-management/limits/#adjustable-service-quotas)
-                or if a **delete** request exceeds the maximum
-                [global limit](/influxdb3/clustered/account-management/limits/#global-limits)
-              - returns `Retry-After` header that describes when to try the write again.
+            Token is temporarily over quota. The Retry-After header describes when to try the write again.
           headers:
             Retry-After:
               description: A non-negative decimal integer indicating the seconds to delay after the response is received.
@@ -2134,7 +2119,6 @@ x-tagGroups:
       - Headers
       - Pagination
       - Response codes
-      - System information endpoints
   - name: All endpoints
     tags:
       - Ping

api-docs/influxdb3/cloud-serverless/v2/ref.yml

@@ -37,21 +37,36 @@ describe('API reference content', () => {
     '/influxdb3/enterprise/api/',
   ];
 
+
   subjects.forEach((subject) => {
     describe(subject, () => {
-      it(`has API info`, function () {
+      beforeEach(() => {
+                // Intercept and modify the page HTML before it loads
+                cy.intercept('GET', '**', (req) => {
+                  req.continue((res) => {
+                    if (res.headers['content-type']?.includes('text/html')) {
+                      // Modify the Kapa widget script attributes
+                      // Avoid socket errors from fpjs in tests by disabling fingerprinting
+                      res.body = res.body.replace(
+                        /data-user-analytics-fingerprint-enabled="true"/,
+                        'data-user-analytics-fingerprint-enabled="false"'
+                      );
+                    }
+                  });
+                });
         cy.visit(subject);
+
+
         window.fcdsc = fakeGoogleTagManager;
         cy.stub(window.fcdsc, 'trackingOptIn').as('trackingOptIn');
         cy.stub(window.fcdsc, 'trackingOptOut').as('trackingOptOut');
+      });
+      it(`has API info`, function () {
+        cy.get('script[data-user-analytics-fingerprint-enabled=false]').should('have.length', 1);
         cy.get('h1').first().should('have.length', 1);
         cy.get('[data-role$=description]').should('have.length', 1);
       });
       it('links back to the version home page', function () {
-        cy.visit(`${subject}`);
-        window.fcdsc = fakeGoogleTagManager;
-        cy.stub(window.fcdsc, 'trackingOptIn').as('trackingOptIn');
-        cy.stub(window.fcdsc, 'trackingOptOut').as('trackingOptOut');
         cy.get('a.back').contains('Docs')
           .should('have.length', 1)
           .click();
@@ -61,10 +76,6 @@ describe('API reference content', () => {
         cy.get('h1').should('have.length', 1);
       });
       it('contains valid internal links', function () {
-        cy.visit(subject);
-        window.fcdsc = fakeGoogleTagManager;
-        cy.stub(window.fcdsc, 'trackingOptIn').as('trackingOptIn');
-        cy.stub(window.fcdsc, 'trackingOptOut').as('trackingOptOut');
         // The following conditional test isn't the cypress way, but the doc might not have internal links.
         cy.get('body').then(($body) => {
           if ($body.find('p a[href^="/"]').length === 0) {
@@ -82,10 +93,6 @@ describe('API reference content', () => {
         });
       });
       it('contains valid external links', function () {
-        cy.visit(subject);
-        window.fcdsc = fakeGoogleTagManager;
-        cy.stub(window.fcdsc, 'trackingOptIn').as('trackingOptIn');
-        cy.stub(window.fcdsc, 'trackingOptOut').as('trackingOptOut');
         // The following conditional test isn't the cypress way, but the doc might not have external links.
         cy.get('body').then(($body) => {
           if ($body.find('p a[href^="http"]').length === 0) {