docs/api-limits: Update 3x security information

https://github.com/hasura/graphql-engine-mono/pull/1873

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
GitOrigin-RevId: 62bfdc6a4cc60be22e0c920601cfd880d9589bc5

docs/graphql/cloud/api-limits.rst

@@ -23,6 +23,21 @@ Configuring an API limit
 **Rate limits**
   Restricts number of GraphQL operations per minute. This uses a sliding window approach. This means whenever Hasura Pro receives a request, it will count the rate of that client starting from the current time to last one minute.
 
+  By default, the rate-limit happens on the ``role_name`` i.e the value provided in ``X-HASURA-ROLE``. But you can also combine additional unique parameters for more granularity.
+  
+  The Unique Parameters that are provided are:
+
+  1. IP Address
+  2. Session Variables
+
+  You can choose any one of the above parameters to rate limit the requests.
+
+  **Note**: If you set an `Unique Parameter` then the combination of both the ``role_name`` and the ``Unique Parameter`` will be used to rate-limit requests.
+  
+  Example:
+
+  If you rate-limit using the ``role_name`` and set the unique parameter for the rate-limit as ``IP Address``, then rate-limit will be applied depending on both those parameteres. i.e If the requests come from a different role but same IP address will **NOT** be rate limited
+
 **Depth limits**
   Restricts a GraphQL operation based on its depth, preventing deeply nested queries.
 
@@ -62,10 +77,92 @@ API limits can have a *global* or *per role* configuration. If an incoming reque
 
   All API limits are **not** applied for the admin role, and depth limits are **NOT** applied to introspection queries
 
-Quick-create limits
--------------------
+Metadata Specification
+----------------------
 
-Hasura Cloud lets you add limits with one click from the list of past operations.
+Hasura provides two metadata API's to manage API limits
 
-.. thumbnail:: /img/graphql/cloud/security/pro-tab-apilimit-config.png
-   :alt: Hasura Cloud Console create new api limit
+Setting API Limits
+~~~~~~~~~~~~~~~~~~
+
+.. code-block:: yaml
+
+
+    type: set_api_limits
+    args:
+      disabled: # Optional Field (Either True or False, The value is False by default)
+
+      depth_limit: # Optional API Limit
+        global: # Mandatory Field
+        per_role: # Optional Field
+          <role_name>: <limit value> # Eg: user: 5
+      
+      node_limit: # Optional API Limit
+        global: # Mandatory Field
+        per_role: # Optional Field
+          <role_name>: <limit value> # Eg: user: 5
+
+      rate_limit: # Optional API Limit
+        global: # Mandatory Field
+          unique_params: # Optional Field, Can either be IP Address or Session variables
+          max_reqs_per_min: # Mandatory Field
+
+        per_role: # Optional Field
+          <role_name>:
+            max_reqs_per_min: # Mandatory Field
+            unique_params: # Optional Field
+
+In the above metadata spec:
+
+1. The API Limits are ``Enabled`` by default, i.e the default value of ``disabled`` is ``False``
+2. When ``disabled`` is `False` and none of the API Limits are set then no API limits are applied.
+3. The ``global`` field in all the API Limits is mandatory, and is used as the default API limit if no ``per_role`` option is set for the user.
+4. The ``per_role`` can be used to override the `global` API Limit value
+5. For ``rate_limit`` if no `unique_params` are provided then, the requests will be rate-limited on the ``role_name`` i.e the ``X-HASURA-ROLE`` that is used to issue the request
+
+Example Metadata Spec:
+
+.. code-block:: yaml
+
+
+    type: set_api_limits
+    args:
+      disabled: false
+
+      depth_limit:
+        global: 5
+        per_role:
+          user: 7
+      
+      node_limit:
+        global: 3
+        per_role:
+          user: 10
+   
+      rate_limit:
+        global:
+          unique_params: IP
+          max_reqs_per_min: 10
+        per_role:
+          anonymous:
+            max_reqs_per_min: 10
+            unique_params: "ip"
+          user:
+            unique_params:
+            - x-hasura-user-id
+            - x-hasura-team-id
+            max_reqs_per_min: 20
+
+
+
+
+Remove API Limits
+~~~~~~~~~~~~~~~~~~
+
+You can remove **all** the api limits that have been set using `remove_api_limit` API.
+
+.. code-block:: yaml
+
+
+    type: remove_api_limits
+    args: {}