docs: console / cli / api workflows (close #3593) (#4948)

#4948
hasura · Oct 13, 2020 · ca3ebdd · ca3ebdd
1 parent 3ea611f
commit ca3ebdd
Show file tree

Hide file tree

Showing 58 changed files with 3,240 additions and 471 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -85,8 +85,9 @@ This release contains the [PDV refactor (#4111)](https://github.com/hasura/graph
 - cli: allow seeds as alias for seed command (#5693)
 - console: remove ONLY as default for ALTER TABLE in column alter operations (close #5512) #5706
 - console: add option to flag an insertion as a migration from `Data` section (close #1766) (#4933)
-- console: add `<3 hasura` section to view updates and notifications from Hasura (#5070)
+- console: add notifications (#5070)
 - docs: add docs page on networking with docker (close #4346) (#4811)
+- docs: add tabs for console / cli / api workflows (close #3593) (#4948)
 - docs: add postgres concepts page to docs (close #4440) (#4471)
 
 

diff --git a/docs/.python-version b/docs/.python-version
@@ -0,0 +1 @@
+3.7.0
diff --git a/docs/_theme/djangodocs/pages/landing.html b/docs/_theme/djangodocs/pages/landing.html
@@ -5,17 +5,32 @@
         <div class="box_head_wrapper">
           <div class="box_head">
             <img src="{{ pathto('_images/landing/graphql.svg', 1) }}" alt="GraphQL engine"/>
-            <h3 class="head_wrapper">Hasura docs</h3>
+            <h3 class="head_wrapper">Hasura Core docs</h3>
           </div>
         </div>
         <div class="space_wrapper text_left">
-          <p class="description">This guide covers all Hasura concepts and features.</p>
+          <p class="description">This guide covers all Hasura Core concepts and features.</p>
           <ul>
             <li>
               <a class="docs_link" href="{{ pathto('graphql/core/index.html', 1) }}">
                 Core docs
               </a>
             </li>
+          </ul>
+        </div>
+      </div>
+    </div>
+    <div class="hcl_half">
+      <div class="box_wrapper">
+        <div class="box_head_wrapper">
+          <div class="box_head">
+            <img src="{{ pathto('_images/landing/graphql.svg', 1) }}" alt="GraphQL engine"/>
+            <h3 class="head_wrapper">Hasura Cloud docs</h3>
+          </div>
+        </div>
+        <div class="space_wrapper text_left">
+          <p class="description">This guide covers all Hasura Cloud concepts and features.</p>
+          <ul>
             <li>
               <a class="docs_link" href="{{ pathto('graphql/cloud/index.html', 1) }}">
                 Cloud docs

diff --git a/docs/graphql/core/actions/action-handlers.rst b/docs/graphql/core/actions/action-handlers.rst
@@ -203,14 +203,54 @@ For your action, add a header that will act as an action secret.
                definition:
                   kind: synchronous
                   handler: http://localhost:3000
-                forward_client_headers: true
-                headers:
-                  - name: ACTION_SECRET
-                    value_from_env: ACTION_SECRET_ENV
+                  forward_client_headers: true
+                  headers:
+                    - name: ACTION_SECRET
+                      value_from_env: ACTION_SECRET_ENV
 
      Save the changes and run ``hasura metadata apply`` to set the
      headers.
 
+  .. tab:: API
+
+    Headers can be set when creating :ref:`creating <create_action>` or :ref:`updating <update_action>` an action via the metadata API.
+
+    .. code-block:: http
+      :emphasize-lines: 12-17
+
+      POST /v1/query HTTP/1.1
+      Content-Type: application/json
+      X-Hasura-Role: admin
+
+      {
+        "type": "create_action",
+        "args": {
+          "name": "addNumbers",
+          "definition": {
+            "kind": "synchronous",
+            "type": "query",
+            "headers": [
+              {
+                "name": "ACTION_SECRET",
+                "value_from_env": "ACTION_SECRET_ENV"
+              }
+            ],
+            "arguments": [
+              {
+                "name": "numbers",
+                "type": "[Int]!"
+              }
+            ],
+            "output_type": "AddResult",
+            "handler": "https://hasura-actions-demo.glitch.me/addNumbers"
+          }
+        }
+      }
+
+    .. note::
+
+      Before creating an action via the :ref:`create_action metadata API <create_action>`, all custom types need to be defined via the :ref:`set_custom_types metadata API <set_custom_types>`.
+
 
 This secret is only known by Hasura and is passed to your endpoint with every call,
 thus making sure only Hasura can successfully authenticate with the action handler.

diff --git a/docs/graphql/core/actions/action-permissions.rst b/docs/graphql/core/actions/action-permissions.rst
@@ -54,3 +54,21 @@ Set action permissions
 
      Save the changes and run ``hasura metadata apply`` to set the
      permissions.
+
+  .. tab:: API
+
+    Action permissions can be set by using the :ref:`create_action_permission metadata API <create_action_permission>`:
+
+    .. code-block:: http
+
+      POST /v1/query HTTP/1.1
+      Content-Type: application/json
+      X-Hasura-Role: admin
+
+      {
+        "type": "create_action_permission",
+        "args": {
+          "action": "insertAuthor",
+          "role": "user"
+        }
+      }
diff --git a/docs/graphql/core/actions/create.rst b/docs/graphql/core/actions/create.rst
@@ -70,6 +70,9 @@ Setup
      Run ``hasura metadata export`` so that you get server's metadata into the
      ``metadata/`` directory.
 
+  .. tab:: API
+
+    There is no setup required for defining actions via the :ref:`actions metadata API <api_actions>`.
 
 Mutation type action
 --------------------
@@ -140,6 +143,67 @@ in the GraphQL schema.
           accessToken: String!
         }
 
+  .. tab:: API
+
+    It is essential that the custom types used in the action are defined *beforehand* via the :ref:`set_custom_types metadata API <set_custom_types>`:
+
+    .. code-block:: http
+
+      POST /v1/query HTTP/1.1
+      Content-Type: application/json
+      X-Hasura-Role: admin
+
+      {
+        "type": "set_custom_types",
+        "args": {
+          "scalars": [],
+          "enums": [],
+          "input_objects": [],
+          "objects": [
+            {
+              "name": "LoginResponse",
+              "fields": [
+                {
+                  "name": "accessToken",
+                  "type": "String!"
+                }
+              ]
+            }
+          ]
+        }
+      }
+
+    Once the custom types are defined, we can create an action via the :ref:`create_action metadata API <create_action>`:
+
+    .. code-block:: http
+
+        POST /v1/query HTTP/1.1
+        Content-Type: application/json
+        X-Hasura-Role: admin
+
+        {
+          "type": "create_action",
+          "args": {
+            "name": "Login",
+            "definition": {
+              "kind": "synchronous",
+              "type": "mutation",
+              "arguments": [
+                {
+                  "name": "username",
+                  "type": "String!"
+                },
+                {
+                  "name": "password",
+                  "type": "String!"
+                }
+              ],
+              "output_type": "LoginResponse",
+              "handler": "https://hasura-actions-demo.glitch.me/login"
+            }
+          }
+        }
+
 The above definition means:
 
 * This action will be available in your GraphQL schema as a mutation called ``login``.
@@ -189,11 +253,14 @@ Now, set the handler for the action:
 
   .. tab:: CLI
 
-     Go to ``metadata/actions.yaml``. You must see a handler like ``http://localhost:3000``
-     or ``http://host.docker.internal:3000`` under the action named ``login``.
-     This is a default value taken from ``config.yaml``.
+    Go to ``metadata/actions.yaml``. You must see a handler like ``http://localhost:3000`` or ``http://host.docker.internal:3000`` under the action named ``login``. This is a default value taken from ``config.yaml``. 
+    Update the ``handler`` to the above endpoint.
 
-     Update the ``handler`` to the above endpoint.
+  .. tab:: API
+
+    The action handler must be set when creating an action via the :ref:`create_action metadata API <create_action>`.
+
+    It can be updated later by using the :ref:`update_action metadata API <update_action>`.
 
 .. admonition:: URL templating
 
@@ -218,12 +285,15 @@ Finally, to save the action:
 
   .. tab:: Console
 
-     Hit ``Create``.
+    Hit ``Create``.
 
   .. tab:: CLI
 
-     Run ``hasura metadata apply``.
+    Run ``hasura metadata apply``.
+
+  .. tab:: API
 
+    An action will be created when sending a request to the :ref:`create_action metadata API <create_action>`.
 
 Step 4: Try it out
 ~~~~~~~~~~~~~~~~~~
@@ -319,6 +389,63 @@ the GraphQL schema.
           sum: Int
         }
 
+  .. tab:: API
+
+    It is essential that the custom types used in the action are defined *beforehand* via the :ref:`set_custom_types metadata API <set_custom_types>`:
+
+    .. code-block:: http
+
+      POST /v1/query HTTP/1.1
+      Content-Type: application/json
+      X-Hasura-Role: admin
+
+      {
+        "type": "set_custom_types",
+        "args": {
+          "scalars": [],
+          "enums": [],
+          "input_objects": [],
+          "objects": [
+            {
+              "name": "AddResult",
+              "fields": [
+                {
+                  "name": "sum",
+                  "type": "Int!"
+                }
+              ]
+            }
+          ]
+        }
+      }
+
+    Once the custom types are defined, we can create an action via the :ref:`create_action metadata API <create_action>`:
+
+    .. code-block:: http
+
+        POST /v1/query HTTP/1.1
+        Content-Type: application/json
+        X-Hasura-Role: admin
+
+        {
+          "type":"create_action",
+            "args": {
+              "name":"addNumbers",
+              "definition": {
+                "kind":"synchronous",
+                "type": "query",
+                "arguments":[
+                  {
+                    "name":"numbers",
+                    "type":"[Int]!"
+                  }
+                ],
+                "output_type":"AddResult",
+                "handler":"https://hasura-actions-demo.glitch.me/addNumbers"
+            }
+          }
+        }
+
 The above definition means:
 
 * This action will be available in your GraphQL schema as a query called ``addNumbers``
@@ -377,6 +504,12 @@ Now, set the handler for the action:
 
      Update the ``handler`` to the above endpoint.
 
+  .. tab:: API
+
+    The action handler must be set when creating an action via the Once the custom types are defined, we can create an action via the :ref:`create_action metadata API <create_action>`.
+
+    It can be updated later by using the :ref:`update_action metadata API <update_action>`.
+
 .. admonition:: URL templating
 
   To manage handler endpoints across environments it is possible to template
@@ -401,6 +534,10 @@ Finally, to save the action:
 
      Run ``hasura metadata apply``.
 
+  .. tab:: API
+
+    An action will be created when sending a request to the :ref:`create_action metadata API <create_action>`.
+
 
 Step 4: Try it out
 ~~~~~~~~~~~~~~~~~~

diff --git a/docs/graphql/core/actions/reuse-types-actions.rst b/docs/graphql/core/actions/reuse-types-actions.rst
@@ -127,3 +127,43 @@ You can create relationships for custom output types by:
 
      Save the changes and run ``hasura metadata apply`` to create the relationship.
 
+  .. tab:: API
+
+    Action relationships can be added while defining custom types via the :ref:`set_custom_types metadata API <set_custom_types>`:
+
+    .. code-block:: http
+      :emphasize-lines: 20-29
+
+      POST /v1/query HTTP/1.1
+      Content-Type: application/json
+      X-Hasura-Role: admin
+
+      {
+        "type": "set_custom_types",
+        "args": {
+          "scalars": [],
+          "enums": [],
+          "input_objects": [],
+          "objects": [
+            {
+              "name": "UpdateAuthorOutput",
+              "fields": [
+                {
+                  "name": "author_id",
+                  "type": "Int!"
+                }
+              ],
+              "relationships": [
+                {
+                  "name": "updatedAuthor",
+                  "type": "object",
+                  "remote_table": "author",
+                  "field_mapping": {
+                    "author_id": "id"
+                  }
+                }
+              ]
+            }
+          ]
+        }
+      }
diff --git a/docs/graphql/core/api-reference/schema-metadata-api/event-triggers.rst b/docs/graphql/core/api-reference/schema-metadata-api/event-triggers.rst
@@ -36,7 +36,7 @@ create_event_trigger
            "name": "sample_trigger",
            "table": {
               "name": "users",
-              "schema": "public",
+              "schema": "public"
            },
            "webhook": "https://httpbin.org/post",
            "insert": {
@@ -116,6 +116,10 @@ Args syntax
      - false
      - Boolean
      - If set to true, the event trigger is replaced with the new definition
+   * - enable_manual
+     - false
+     - Boolean
+     - If set to true, the event trigger can be invoked manually 
 
 (*) Either ``webhook`` or ``webhook_from_env`` are required.