docs: update actions documentation (#4586)

CHANGELOG.md

@@ -59,6 +59,7 @@ using this flag is insecure since verification is not carried out.
 - console: fix table columns type comparision during column edit (close #4125) (#4393)
 - cli: allow initialising project in current directory (fix #4560) #4566
 - cli: remove irrelevant flags from init command (close #4508) (#4549)
+- docs: update actions docs (#4586)
 
 ## `v1.2.0-beta.5`
 

docs/graphql/manual/actions/action-permissions.rst

@@ -0,0 +1,56 @@
+.. meta::
+   :description: Permissions for Hasura actions
+   :keywords: hasura, docs, actions, permissions
+
+.. _actions_permissions:
+
+Actions permissions
+===================
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 2
+  :local:
+
+Introduction
+------------
+
+As with the other fields in the GraphQL schema, users need to be
+given access to an action.
+
+Set action permissions
+----------------------
+
+.. rst-class:: api_tabs
+.. tabs::
+
+  .. tab:: Console
+
+     Head to the ``Actions -> [action-name] -> Permissions`` tab in the
+     console.
+
+     .. thumbnail:: ../../../img/graphql/manual/actions/actions-permissions.png
+        :alt: Console action permission
+
+     Hit ``Save`` to give the role permission to access the action.
+
+  .. tab:: CLI
+
+     Go to ``metadata/actions.yaml`` in the Hasura project directory.
+
+     Update the definition of the ``insertAuthor`` action as:
+
+     .. code-block:: yaml
+       :emphasize-lines: 6-8
+
+         - actions
+           - name: insertAuthor
+             definition:
+               kind: synchronous
+               handler: '{{ACTIONS_BASE_URL}}/insertAuthor'
+             permissions:
+             - role: user
+             - role: publisher
+
+     Save the changes and run ``hasura metadata apply`` to set the
+     permissions.

docs/graphql/manual/actions/create.rst

@@ -38,9 +38,8 @@ Setup
 
   .. tab:: CLI
 
-     .. :ref:`Install <install_hasura_cli>` or :ref:`update to <hasura_update-cli>` the latest version of Hasura CLI.
+     :ref:`Install <install_hasura_cli>` or :ref:`update to <hasura_update-cli>`
-
+     the latest version of Hasura CLI.
-     Download the latest pre-release CLI version from the `releases page <https://github.com/hasura/graphql-engine/releases>`_
 
      You can either get started with an existing project or create a new project.
 
@@ -61,8 +60,8 @@ Setup
      Actions are supported only in the v2 config of the CLI. Check the ``config.yaml``
      of your Hasura project for the ``version`` key.
 
-     If you are in ``version: 1``, actions commands are not supported. Upgrade to
+     If you see ``version: 1`` (or do not see a version key), upgrade to version
-     version 2 by running:
+     2 by running:
 
      .. code-block:: bash
 
@@ -78,10 +77,16 @@ Mutation type action
 Let's start with a mutation that accepts a username and password, and returns
 an access token. We'll call this mutation ``login``.
 
+.. contents::
+  :backlinks: none
+  :depth: 1
+  :local:
+
 Step 1: Define your mutation and associated types
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Start with defining the mutation and the required types. These types will reflect in the GraphQL schema.
+Start with defining the mutation and the required types. These types will reflect
+in the GraphQL schema.
 
 .. rst-class:: api_tabs
 .. tabs::
@@ -93,6 +98,7 @@ Start with defining the mutation and the required types. These types will reflec
 
      .. thumbnail:: ../../../img/graphql/manual/actions/mutation-action-create.png
         :alt: Console action create
+        :width: 70%
 
      Define the action as follows in the ``Action Definition`` editor.
 
@@ -145,7 +151,10 @@ Step 2: Create the action handler
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 A handler is an HTTP webhook where you can perform the custom logic for the
-action. In this case, we will just return an access token, but typically you would want to run all the business logic that the action demands. NodeJS/Express code
+action.
+
+In this case, we will just return an access token, but typically you would want
+to run all the business logic that the action demands. NodeJS/Express code
 for this handler would look something like:
 
 .. code-block:: js
@@ -241,10 +250,17 @@ Query type action
 Let's start with a basic query that accepts a list of numbers and returns
 their sum. We'll call this query ``addNumbers``.
 
-Step 1: Define your query and associated types
+.. contents::
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+  :backlinks: none
+  :depth: 1
+  :local:
 
-Start with defining the query and the required types. These types will reflect in the GraphQL schema.
+
+Step 1: Define your query and associated types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Start with defining the query and the required types. These types will reflect in
+the GraphQL schema.
 
 .. rst-class:: api_tabs
 .. tabs::
@@ -256,6 +272,7 @@ Start with defining the query and the required types. These types will reflect i
 
      .. thumbnail:: ../../../img/graphql/manual/actions/query-action-create.png
         :alt: Console action create
+        :width: 70%
 
      Define the action as follows in the ``Action Definition`` editor.
 
@@ -308,7 +325,9 @@ Step 2: Create the action handler
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 A handler is an HTTP webhook where you can perform the custom logic for the
-action. In this case, it is the addition of the numbers. NodeJS/Express code
+action.
+
+In this case, it is the addition of the numbers. NodeJS/Express code
 for this handler would look something like:
 
 .. code-block:: js

docs/graphql/manual/actions/debugging.rst

@@ -12,69 +12,66 @@ Debugging actions
   :depth: 1
   :local:
 
-While you're developing actions for your application, you may want to debug the webhook
+While you're developing actions for your application, to debug faster you may
-configured for the action. To do so, start the server in :ref:`debugging mode <errors-debugging>`.
+want to see the exact details of the webhook call for the action
-In the case of errors, the GraphQL response contains debugging information of webhook
+as well.
-calls in the ``extensions.internal`` field.
 
-For example, let's consider the following mutation:
+To do so, start the server in :ref:`debugging mode <errors-debugging>`.
+In the case of errors, the GraphQL response will contain debugging information
+of the webhook calls in the ``extensions.internal`` field.
 
-.. code-block:: graphql
+**For example**:
 
-      mutation {
+.. graphiql::
+  :view_only:
+  :query:
+    mutation {
         create_user(email: "foo@bar.com", name: "Foo"){
           id
           user {
             name
             email
-            is_admin
           }
         }
       }
-
+  :response:
-In case of errors, the response will look like the following if the debugging mode is enabled.
-
-.. code-block:: json
-
     {
       "errors": [
         {
+          "message": "expecting object or array of objects for action webhook response",
           "extensions": {
+            "code": "parse-failed",
+            "path": "$",
             "internal": {
+              "error": "expecting object or array of objects for action webhook response",
               "response": {
                 "status": 200,
-                "body": "some-string",
                 "headers": [
                   {
                     "value": "application/json",
                     "name": "Content-Type"
                   }
-                ]
+                ],
+                "body": "[incorrect response]"
               },
               "request": {
+                "url": "http://127.0.0.1:5593/invalid-response",
+                "headers": [],
                 "body": {
+                  "action": {
+                    "name": "create_user"
+                  },
                   "session_variables": {
                     "x-hasura-role": "admin"
                   },
                   "input": {
                     "email": "foo@boo.com",
                     "name": "Foo"
-                  },
-                  "action": {
-                    "name": "create_user"
                   }
-                },
+                }
-                "url": "http://127.0.0.1:5593/invalid-response",
+              }
-                "headers": [
+            }
-
+          }
-                ]
-              },
-              "error": "expecting object or array of objects for action webhook response"
-            },
-            "path": "$",
-            "code": "parse-failed"
-          },
-          "message": "expecting object or array of objects for action webhook response"
         }
       ]
     }

docs/graphql/manual/actions/derive.rst

@@ -16,11 +16,11 @@ Introduction
 ------------
 
 It is a typical requirement to run some custom business logic before actually
-executing a mutation, for example, to perform validations or to enrich some data
+executing a mutation / query, for example, to perform validations or to enrich
-from an external source. Actions can be used to achieve this.
+some data from an external source. Actions can be used to achieve this.
 
 To help with creation of such actions, Hasura lets you derive an action from an
-existing query or a mutation by:
+existing query or mutation by:
 
 - Auto-generating the GraphQL types defining the action
 - Generating the handler code to delegate the action back to the original query or mutation
@@ -133,7 +133,6 @@ derive our action:
     output type.
 
 
-
 Generate handler code for a derived action
 ------------------------------------------
 
@@ -175,3 +174,17 @@ the action back to the original operation.
     .. code-block:: bash
 
         hasura actions codegen <action-name> --derive-from '<query/mutation string>'
+
+Hiding the original mutation in the API
+---------------------------------------
+
+Once a mutation is derived, you might want to hide it from your public
+GraphQL API but still want to use it from your action handler.
+
+To achieve this you can mark the mutation as ``backend_only`` so that it
+can be accessed only via "trusted sources". See :ref:`backend-only-permissions`
+for more details
+
+.. note::
+
+  Setting ``backend-only`` is currently available for insert mutations only.

docs/graphql/manual/actions/index.rst

@@ -4,8 +4,8 @@
 
 .. _actions:
 
-Actions (beta)
+Actions
-==============
+=======
 
 .. contents:: Table of contents
   :backlinks: none
@@ -20,17 +20,13 @@ logic using custom queries and mutations. Actions can be
 added to Hasura to handle various use cases such as data validation, data
 enrichment from external sources and any other complex business logic.
 
-.. thumbnail:: ../../../img/graphql/manual/actions/actions-hl-arch.png
+.. thumbnail:: ../../../img/graphql/manual/actions/actions-arch.png
    :class: no-shadow
    :alt: Actions high level architecture
 
-.. admonition:: Supported from
+.. admonition:: Support
 
-   Actions are currently available in beta in the pre-release versions of ``v1.2.0``.
+   Actions are supported in Hasura GraphQL engine versions ``v.1.2.0`` and above.
-
-   .. Actions are supported in versions ``v.1.2.0`` and above.
-
-.. admonition:: Postgres support
 
    Actions are supported for ``Postgres versions 10 or higher``.
 
@@ -42,20 +38,22 @@ An action consists of the following parts:
 1. ``Type``: The type of the action (``query`` or ``mutation``)
 2. ``Definition``: The definition of the query or mutation
 3. ``Handler``: The logic to be run when the query or mutation is executed
-4. ``Kind``: Sync or async
+4. ``Kind``: Sync or async. In case of a query action, there is no ``Kind``
-
+   associated with it. A query action is always sync
-.. note::
-
-      In case of a query action, there is no ``Kind`` associated with the action.
-      A query action works like a ``Synchronous`` mutation action.
 
 Type
 ****
 
 Actions can be of two types:
 
-- **Query action**: An action of type ``query`` extends the query root of the Hasura schema. This means that you can execute this action through a GraphQL query. Query actions must be used where you want to fetch data from a data source without changing anything on the data source.
+- **Query action**: An action of type ``query`` extends the query root of the
-- **Mutation action**: An action of type ``mutation`` extends the mutation root of the Hasura schema. This means that you can execute this action through a GraphQL mutation. Mutation actions must be used when you want to mutate the state of a data source and fetch some data.
+  Hasura schema. This means that you can execute this action through a GraphQL query.
+  Query actions must be used where you want to fetch data from a data source without
+  changing anything on the data source.
+- **Mutation action**: An action of type ``mutation`` extends the mutation root of
+  the Hasura schema. This means that you can execute this action through a GraphQL
+  mutation. Mutation actions must be used when you want to mutate the state of a data
+  source and fetch some data.
 
 Definition
 **********
@@ -112,16 +110,16 @@ Learn more about :ref:`writing an action handler<action_handlers>`.
 Kind
 ****
 
-Mutation actions are of two kinds:
+**Mutation actions** are of two kinds:
 
-* **Synchronous actions**: Sync actions return a response to the client after
+* **Synchronous**: Sync actions return a response to the client after
   receiving a response from the handler.
-* **Asynchronous actions**: :ref:`Async actions <async_actions>` return an
+* **Asynchronous**: :ref:`Async actions <async_actions>` return an
   ``action id`` as response to the client before receiving a response from the
   handler and allow the client to subscribe to the actual response using the
   ``action id``.
 
-Query actions don't have a kind, they always behave like ``Synchronous mutation actions``.
+**Query actions** don't have a kind, they always behave like sync mutation actions.
 
 How it works?
 -------------
@@ -148,5 +146,6 @@ Learn more
   async-actions
   Codegen <codegen>
   derive
+  action-permissions
   action-connect
   debugging

docs/graphql/manual/auth/authorization/permission-rules.rst

@@ -250,12 +250,17 @@ or static data instead.
 
 .. _backend-only-permissions:
 
-Backend only inserts
+Backend only
-^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^
 
-If an insert mutation permission is marked as ``backend_only``, the mutation is accessible to the
+If a permission is marked as ``backend_only``, the mutation is accessible to the
 given role only if ``x-hasura-use-backend-only-permissions`` session variable exists and is set to ``true``
 and request is made with ``x-hasura-admin-secret`` set if any auth is configured.
 
 This might be useful if you would like to hide a mutation from the public facing API but allow access to it
 via a "trusted backend".
+
+.. note::
+
+  Setting ``backend-only`` is currently available for insert mutations only.
+

docs/graphql/manual/deployment/graphql-engine-flags/config-examples.rst

@@ -173,7 +173,7 @@ the right content-type headers.
 .. _errors-debugging:
 
 Debugging mode
-----------------
+--------------
 
 The Hasura GraphQL engine may provide additional information for each object in the ``extensions`` key of ``errors``.
 The ``internal`` key contains error information including the

docs/graphql/manual/event-triggers/index.rst

@@ -17,6 +17,7 @@ events on specified tables and invoke webhooks to carry out any custom logic.
 
 .. thumbnail:: ../../../img/graphql/manual/event-triggers/database-event-triggers.png
    :class: no-shadow
+   :width: 80%
    :alt: Hasura event trigger architecture
 
 Events can be of the following types:

docs/graphql/manual/remote-schemas/index.rst

@@ -25,7 +25,7 @@ This is what Hasura running with "Remote schemas" looks like:
 
 .. thumbnail:: ../../../img/graphql/manual/remote-schemas/remote-schemas-arch.png
    :class: no-shadow
-   :width: 75%
+   :width: 55%
    :alt: Architecture of Hasura with remote schemas
 
 .. note::