From 92b115b1b490e004dde19c8d87730dec98823ca1 Mon Sep 17 00:00:00 2001
From: Jason Stirnaman <stirnamanj@gmail.com>
Date: Wed, 25 Sep 2024 16:31:55 -0500
Subject: [PATCH] fix(api): Fix Cloud Dedicated /ping descriptions

- Cloud Dedicated /ping only reports querier, not ingester, health
- Update v1 docs API and client library recommendations.

Closes 5610
---
 .../v1-compatibility/swaggerV1Compat.yml      | 77 +++++++++++++++++++
 api-docs/cloud-dedicated/v2/ref.yml           | 22 ++++--
 2 files changed, 91 insertions(+), 8 deletions(-)

diff --git a/api-docs/cloud-dedicated/v1-compatibility/swaggerV1Compat.yml b/api-docs/cloud-dedicated/v1-compatibility/swaggerV1Compat.yml
index 091885223..e13b311fe 100644
--- a/api-docs/cloud-dedicated/v1-compatibility/swaggerV1Compat.yml
+++ b/api-docs/cloud-dedicated/v1-compatibility/swaggerV1Compat.yml
@@ -240,6 +240,83 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
+  /ping:
+    get:
+      description: |
+        Reports the InfluxQL bridge querier health and the InfluxDB version of the instance.
+        
+        The response is a HTTP `204` status code to inform you the querier is available.
+
+        For InfluxDB Cloud Dedicated, this endpoint only checks the status of queriers; doesn't check the status of ingesters.
+
+        To check the health of ingesters before writing data, send a request to one of the [write endpoints](/influxdb/cloud-dedicated/api/v2/#tag/Write).
+
+        This endpoint doesn't require authentication.
+      operationId: GetPing
+      responses:
+        '204':
+          description: |
+            Success--the querier is available.
+            Headers contain InfluxDB version information.
+          headers:
+            X-Influxdb-Build:
+              description: |
+                The type of InfluxDB build.
+              schema:
+                type: string
+            X-Influxdb-Version:
+              description: |
+                The version of InfluxDB.
+              schema:
+                type: integer
+        4xx:
+          description: |
+            #### InfluxDB Cloud
+            - Doesn't return this error.
+      security:
+        - {}
+      servers: []
+      summary: Get the status of the instance
+      tags:
+        - Ping
+    head:
+      description: |
+        Reports the InfluxQL bridge querier health and the InfluxDB version of the instance.
+        
+        The response is a HTTP `204` status code to inform you the querier is available.
+
+        For InfluxDB Cloud Dedicated, this endpoint only checks the status of queriers; doesn't check the status of ingesters.
+
+        To check the health of ingesters before writing data, send a request to one of the [write endpoints](/influxdb/cloud-dedicated/api/v2/#tag/Write).
+
+        This endpoint doesn't require authentication.
+
+      operationId: HeadPing
+      responses:
+        '204':
+          description: |
+            Success--the querier is available.
+            Headers contain InfluxDB version information.
+          headers:
+            X-Influxdb-Build:
+              description: The type of InfluxDB build.
+              schema:
+                type: string
+            X-Influxdb-Version:
+              description: |
+                The version of InfluxDB.
+              schema:
+                type: integer
+        4xx:
+          description: |
+            #### InfluxDB Cloud
+            - Doesn't return this error.
+      security:
+        - {}
+      servers: []
+      summary: Get the status of the instance
+      tags:
+        - Ping
 components:
   parameters:
     TraceSpan:
diff --git a/api-docs/cloud-dedicated/v2/ref.yml b/api-docs/cloud-dedicated/v2/ref.yml
index 15dbd9307..b223b244e 100644
--- a/api-docs/cloud-dedicated/v2/ref.yml
+++ b/api-docs/cloud-dedicated/v2/ref.yml
@@ -149,17 +149,20 @@ paths:
   /ping:
     get:
       description: |
-        Retrieves the status and InfluxDB version of the instance.
+        Reports the InfluxQL bridge querier health and the InfluxDB version of the instance.
+        
+        The response is a HTTP `204` status code to inform you the querier is available.
 
-        Use this endpoint to monitor uptime for the InfluxDB instance. The response
-        returns a HTTP `204` status code to inform you the instance is available.
+        For InfluxDB Cloud Dedicated, this endpoint only checks the status of queriers; doesn't check the status of ingesters.
+
+        To check the health of ingesters before writing data, send a request to one of the [write endpoints](/influxdb/cloud-dedicated/api/v2/#tag/Write).
 
         This endpoint doesn't require authentication.
       operationId: GetPing
       responses:
         '204':
           description: |
-            Success.
+            Success--the querier is available.
             Headers contain InfluxDB version information.
           headers:
             X-Influxdb-Build:
@@ -184,17 +187,20 @@ paths:
         - Ping
     head:
       description: |
-        Returns the status and InfluxDB version of the instance.
+        Reports the InfluxQL bridge querier health and the InfluxDB version of the instance.
+        
+        The response is a HTTP `204` status code to inform you the querier is available.
 
-        Use this endpoint to monitor uptime for the InfluxDB instance. The response
-        returns a HTTP `204` status code to inform you the instance is available.
+        For InfluxDB Cloud Dedicated, this endpoint only checks the status of queriers; doesn't check the status of ingesters.
+
+        To check the health of ingesters before writing data, send a request to one of the [write endpoints](/influxdb/cloud-dedicated/api/v2/#tag/Write).
 
         This endpoint doesn't require authentication.
       operationId: HeadPing
       responses:
         '204':
           description: |
-            Success.
+            Success--the querier is available.
             Headers contain InfluxDB version information.
           headers:
             X-Influxdb-Build: