add dedicated version and health api docs pages (#3482)

docs/graphql/manual/api-reference/health.rst

@@ -0,0 +1,67 @@
+.. _health_api_reference:
+
+Health check API Reference
+==========================
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+The Health API is a public endpoint which gives info on the server health.
+
+Endpoint
+--------
+
+All requests are ``GET`` requests to the ``/healthz`` endpoint.
+
+API Spec
+--------
+
+Request
+^^^^^^^
+
+.. code-block:: http
+
+   GET /healthz HTTP/1.1
+
+Response
+^^^^^^^^
+
+Depending on the server health status any of the following responses can be returned:
+
+.. list-table::
+  :header-rows: 1
+
+  * - Server condition
+    - HTTP Status
+    - Message
+  * - All healthy
+    - 200
+    - OK
+  * - Serving requests but some metadata objects are inconsistent/not-available
+    - 200
+    - WARN: inconsistent objects in schema
+  * - Unhealthy
+    - 500
+    - ERROR
+
+.. note::
+
+  If there are metadata inconsistencies, you should use the Hasura console or the
+  `get_inconsistent_metadata <schema-metadata-api/manage-metadata.html#get-inconsistent-metadata>`_ API to find out what
+  the inconsistent objects are and resolve them.
+
+
+Sample response
+***************
+
+.. code-block:: http
+
+   HTTP/1.1 200 OK
+
+
+Disabling Health check API
+--------------------------
+
+The ``healthz`` API endpoint is public and cannot be disabled

docs/graphql/manual/api-reference/index.rst

@@ -55,38 +55,18 @@ See details at :doc:`schema-metadata-api/index`.
 Version API
 ^^^^^^^^^^^
 
-A ``GET`` request to the public ``/v1/version`` endpoint responds with the current server version
+The ``/v1/version`` is a public endpoint that responds with the current server version in JSON format.
-in JSON format:
 
-.. code-block:: js
+See details at :doc:`version`.
-
-   {"version": "v1.0.0-alpha01"}
 
 .. _health_api:
 
 Health check API
 ^^^^^^^^^^^^^^^^
 
-A ``GET`` request to the public ``/healthz`` endpoint will respond with the following:
+The ``/healthz`` is a public endpoint that returns the server health status.
-
-.. list-table::
-   :header-rows: 1
-
-   * - Server condition
-     - HTTP Status
-     - Message
-   * - All healthy
-     - 200
-     - OK
-   * - Serving requests but some metadata objects are inconsistent/not-available
-     - 200
-     - WARN: inconsistent objects in schema
-   * - Unhealthy
-     - 500
-     - ERROR
-
-If there are metadata inconsistencies, you should use the console or use the `get_inconsistent_metadata <schema-metadata-api/manage-metadata.html#get-inconsistent-metadata>`_ API to find out what the inconsistent objects are.
 
+See details at :doc:`health`.
 
 .. _pg_dump_api:
 
@@ -122,6 +102,8 @@ You can refer to the following to know about all PostgreSQL types supported by t
 
   GraphQL API <graphql-api/index>
   Schema / Metadata APIs <schema-metadata-api/index>
+  Version API <version>
+  Health check API <health>
   PG Dump API <pgdump>
   Config API <config>
   Supported PostgreSQL types <postgresql-types>

docs/graphql/manual/api-reference/version.rst

@@ -0,0 +1,45 @@
+.. _version_api_reference:
+
+Version API Reference
+=====================
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+
+The ``/v1/version`` is a public endpoint that responds with the current server version in JSON format.
+
+Endpoint
+--------
+
+All requests are ``GET`` requests to the ``/v1/version`` endpoint.
+
+API Spec
+--------
+
+Request
+^^^^^^^
+
+.. code-block:: http
+
+   GET /v1/version HTTP/1.1
+
+
+Sample response
+^^^^^^^^^^^^^^^
+
+.. code-block:: http
+
+   HTTP/1.1 200 OK
+   Content-Type: application/json
+
+   {
+     "version": "v1.0.0-alpha01"
+   }
+
+Disabling Version API
+---------------------
+
+The ``version`` API endpoint is public and cannot be disabled.