docs: add actions docs (hasura#3907)

Author: rikinsk

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

@@ -0,0 +1,123 @@
+Action handlers
+===============
+
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Introduction
+------------
+
+Actions need to be backed by custom business logic. This business logic can be
+defined in a handler which is an HTTP webhook.
+
+
+HTTP handler
+------------
+
+When the action mutation is called, Hasura makes a ``POST`` request to the
+handler with the mutation arguments and the session variables.
+
+The request payload is of the format:
+
+.. code-block:: json
+
+    {
+      "action": "<action-name>",
+      "input": {
+        "arg1": "<value>",
+        "arg2": "<value>"
+      },
+      "session_variables": {
+        "x-hasura-user-id": "<session user id>",
+        "x-hasura-role": "<session user role>"
+      }
+    }
+
+
+Returning a success response
+----------------------------
+
+To return a success response, you must send back a response payload of action's
+response type. The HTTP status code must be ``2xx`` for a successful response.
+
+Returning an error response
+---------------------------
+
+To return an error response, you must send back an error object or a list of
+error objects. An error object looks like:
+
+.. code-block:: json
+
+    {
+      "message": "<error message>"
+    }
+
+The HTTP status code must be ``4xx`` for an error response.
+
+
+Example
+-------
+
+For example, consider the following mutation.
+
+.. code-block:: graphql
+
+    extend type Mutation {
+      UserLogin (username: String!, email: String!): UserInfo
+    }
+
+    type UserInfo {
+      accessToken: String!
+      userId: Int!
+    }
+
+Let's say, the following mutation is executed:
+
+.. code-block:: graphql 
+
+    mutation {
+      UserLogin (username: "jake", password: "secretpassword") {
+        accessToken
+        userId
+      }
+    }
+
+
+Hasura will call the handler with the following payload:
+
+.. code-block:: json
+
+    {
+      "action": "UserInfo",
+      "input": {
+        "username": "jake",
+        "password": "secretpassword"
+      },
+      "session_variables": {
+        "x-hasura-user-id": "423",
+        "x-hasura-role": "user"
+      }
+    }
+
+To return a success response, you must send the response of the action's output
+type (in this case, ``UserInfo``) with a status code ``2xx``. So a sample
+response would be:
+
+.. code-block:: json
+
+    {
+      "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVC",
+      "userId": 4829
+    }
+
+To throw an error, you must a response payload of the followin type while
+setting the status code as ``4xx``.
+
+.. code-block:: json
+
+   {
+     "message": "invalid credentials"
+   }

docs/graphql/manual/actions/async-actions.rst

@@ -0,0 +1,48 @@
+Async actions
+=============
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Sometimes you may not want to wait for an action to complete before sending a
+response back to the client (say if the business logic takes a long time). In
+such cases you can create an **asynchronous** action, which returns an
+``action_id`` immediately to the client before contacting the handler.
+
+If you mark an action as **asynchronous**, Hasura also generates a
+``query`` and a ``subscription`` field for the action so that you can
+query/subscribe to its status.
+
+For example, let's say ``place_order`` is an asynchronous action
+
+.. code-block:: graphql
+
+   mutation placeOrderRequest($order_input: place_order_input!) {
+     place_order(input: $order_input) 
+   }
+
+Executing this mutation will return a response like:
+
+.. code-block:: json
+
+   {
+     "data": {
+       "place_order": "23b1c256-7aff-4b95-95bd-68220d9f93f2"
+     }
+   }
+
+The returned ``uuid`` is the ``action id`` of the async action. To get the actual
+response of the action, you can ``query`` or ``subscribe`` to the action
+using this ``action id``.
+
+.. code-block:: graphql
+
+    subscription getPlaceOrderResponse {
+      place_order (id: "23b1c256-7aff-4b95-95bd-68220d9f93f2") {
+        output
+        errors
+      }
+    }
+

docs/graphql/manual/actions/codegen.rst

@@ -0,0 +1,111 @@
+Actions codegen
+===============
+
+.. contents:: Table of contents
+  :backlinks: none
+  :depth: 1
+  :local:
+
+Introduction
+------------
+
+Actions need HTTP handlers to run the business logic. It might be inconvenient
+to write the complete handler code for every action. Luckily, GraphQL's type
+system allows us to auto-generate the boilerplate code for actions.
+
+
+.. note::
+
+  Hasura currently has codegen set up for a few frameworks. The list of
+  supported frameworks should grow with contributions from the
+  community.
+
+Generating handler code for your action
+---------------------------------------
+
+.. rst-class:: api_tabs
+.. tabs::
+
+  .. tab:: Console
+
+    Head to the ``Actions -> [action-name] -> Codegen`` tab in the console
+
+    You can select the framework of your choice to get the corresponding
+    handler boilerplate code.
+
+    .. thumbnail:: ../../../img/graphql/manual/actions/codegen/console-codegen-tab.png
+       :alt: Console codegen tab
+
+
+  .. tab:: CLI
+
+    **Configuration**
+
+    Before being able to codegen for actions, you have to configure your CLI.
+
+    Run:
+
+    .. code-block:: bash
+
+       hasura actions use-codegen
+
+    1. Choose which framework you want to codegen for:
+
+       .. thumbnail:: ../../../img/graphql/manual/actions/codegen/cli-framework-prompt.png
+          :alt: CLI Framework Prompt
+
+    2. Choose if you also wish to clone a starter kit for the chosen framework:
+
+       .. thumbnail:: ../../../img/graphql/manual/actions/codegen/cli-starter-kit-prompt.png
+          :alt: CLI Starter Kit Prompt
+
+    3. Choose a path where you want to output the auto-generated code files
+
+       .. thumbnail:: ../../../img/graphql/manual/actions/codegen/cli-output-dir-prompt.png
+          :alt: CLI Starter Kit Prompt
+
+
+    This command will update your ``config.yaml`` with the codegen config as per
+    your preferences. You can also set these values manually in ``config.yaml``.
+
+    For example:
+
+    .. code-block:: yaml
+       :emphasize-lines: 8-10
+
+        version: "2"
+        endpoint: http://localhost:8080
+        metadata_directory: metadata
+        migrations_directory: migrations
+        actions:
+          handler_webhook_baseurl: http://localhost:3000
+          kind: synchronous
+          codegen:
+            framework: nodejs-express
+            output_dir: ./nodejs-express/src/handlers/
+
+
+
+    **Codegen**
+
+
+    To finally get auto-generated code for an action, run:
+
+    .. code-block:: bash
+
+       hasura actions codegen <action-name>
+
+    The codegen files will be generated at the ``output_dir`` path from ``config.yaml``.
+
+
+Building a codegen for your framework
+-------------------------------------
+
+As of now, Hasura provides codegen for a few frameworks (``nodejs-express``,
+``typescript-zeit``, etc).
+
+If you wish to build a code generator for your framework
+`read the contrib guide <https://github.com/hasura/codegen-builder-contrib/>`_.
+
+
+