graphql-engine/docs/graphql/core/actions/transforms.rst

.. meta::
   :description: Transform actions requests
   :keywords: hasura, docs, action, transforms, rest connectors

.. _action_transforms:

Actions transforms
==================

.. contents:: Table of contents
  :backlinks: none
  :depth: 2
  :local:

Introduction
------------

Transforms are used to perform custom transformations on the HTTP
request generated by an action. This can be used to integrate any existing API
without needing to write or deploy any middleware code. Action transforms can be seen as "REST connectors"
as you can integrate any REST endpoint as a GraphQL API with a suitable transformation.

.. admonition:: Supported from

  Transforms are supported in Hasura GraphQL Engine versions ``v2.1.0`` and above

Configuring actions transforms
------------------------------

.. rst-class:: api_tabs
.. tabs::

  .. tab:: Console

    Go to the ``Actions`` tab on the console and create or modify an action. Scroll down to ``Configure Transformations`` section:

    .. thumbnail:: /img/graphql/core/actions/configure-transformation.png
       :alt: Configure action transformation
       :width: 70%


  .. tab:: API

    Action transforms can be added to actions using the :ref:`create_action metadata API <metadata_create_action>` or
    :ref:`update_action metadata API <metadata_update_action>` by adding a
    :ref:`request_transform <RequestTransformation>` field to the args:


    .. code-block:: http
       :emphasize-lines: 24-26

       POST /v1/metadata HTTP/1.1
       Content-Type: application/json
       X-Hasura-Role: admin

       {
          "type":"create_action",
          "args":{
             "name":"create_user",
             "definition":{
                "kind":"synchronous",
                "arguments":[
                   {
                      "name":"username",
                      "type":"String!"
                   },
                   {
                      "name":"email",
                      "type":"String!"
                   }
                ],
                "output_type":"User",
                "handler":"https://action.my_app.com/create-user",
                "timeout":60,
                "request_transform": {
                   "body": "{{$body.input.name}}"
                },
             },
            "comment": "Custom action to create user"
          }
       }

Types of transformations
------------------------

You can practically create an arbitrary request using the context available in the Action execution.
The context variables available during transformation are:

.. list-table::
   :header-rows: 1

   * - Context variable
     - Value
   * - $body
     - Original body of action request
   * - $base_url
     - Original configured URL
   * - $session_variables
     - Session variables 

Request body
************

Generate a custom body by giving a ``body`` key to the ``request_transform``.
You can use the `Kriti templating language <https://github.com/hasura/kriti-lang>`__ to construct the body.

.. rst-class:: api_tabs
.. tabs::


  .. tab:: Console

    In the ``Configure Transformations`` section, click on ``Add Payload Transformation``:

    .. thumbnail:: /img/graphql/core/actions/payload-transformation.png
       :alt: Add payload transformation
       :width: 90%


  .. tab:: API

    .. code-block:: json
      :emphasize-lines: 3-6

      {
        "request_transform": {
           "body": {
               "name": "{{$body.input.name}}",
               "email": "{{$body.input.email}}"
           }
        }
      }

Content Type
************

You can change the ``Content-Type`` of the request to either ``application/json`` or ``x-www-form-urlencoded``. The default is ``application/json``.

.. rst-class:: api_tabs
.. tabs::

  .. tab:: Console

    Console support coming soon.

  .. tab:: API

    .. code-block:: json
      :emphasize-lines: 7

      {
        "request_transform": {
           "body": {
               "name": "{{$body.input.name}}",
               "email": "{{$body.input.email}}",
           },
           "content_type": "x-www-form-urlencoded"
        }
      }

With ``x-www-form-urlencoded``,  the key-value pairs in ``body`` are transformed to ``name={{$body.input.name}}&key2={{$body.input.email}}``.

URL
***

Transform the request URL. This can be used to embed, say user-id, in the url path.
You can also provide ``query_params`` to add to the URL.
You can use the `Kriti templating language <https://github.com/hasura/kriti-lang>`__ to construct any string value here.

.. rst-class:: api_tabs
.. tabs::
  .. tab:: Console

    In the ``Configure Transformations`` section, click on ``Add Request Options Transformation``:

    .. thumbnail:: /img/graphql/core/actions/request-options-transformation.png
       :alt: Console action create
       :width: 90%

  .. tab:: API

    .. code-block:: json
      :emphasize-lines: 3

      {
        "request_transform": {
          "url": "{{$base_url}}/{{$session_variables['x-hasura-user-id']}}",
          "query_params": {
             "param1": "{{$body.input.value1}}",
             "param2": "{{$body.input.value2}}"
          }
        }
      }

.. admonition:: escapeUri

  Note that you must use the ``escapeUri`` function to urlencode templated values.
  For example, if you have to use session variables in the URL and those may contain non-ASCII values,
  then you should provide the template URL as ``{{$base_url}}/{{escapeUri $session_variables['x-hasura-user-id']}}``

Method
******

Transform the method. This can be used to change the request method, say from ``POST`` to ``GET``, as shown below.

.. rst-class:: api_tabs
.. tabs::

  .. tab:: Console

    In the ``Configure Transformations`` section, click on ``Add Request Options Transformation``:

    .. thumbnail:: /img/graphql/core/actions/request-options-transformation.png
       :alt: Console action create
       :width: 90%

  .. tab:: API

    .. code-block:: json
      :emphasize-lines: 3

      {
        "request_transform": {
           "method": "GET",
           "url": "$base_url/{{$session_variables['x-hasura-user-id']}}"
        }
      }

Example
-------

Let's integrate Auth0's management API to update the profile of a user:

.. rst-class:: api_tabs
.. tabs::


  .. tab:: Console

    Go to the ``Actions`` tab on the console and create or modify an action. Scroll down to ``Configure Transformations`` section:

    Action definition:

    .. thumbnail:: /img/graphql/core/actions/example-transformation-0.png
       :alt: Console action create
       :width: 90%

    The transformation is given by:

    .. thumbnail:: /img/graphql/core/actions/example-transformation-1.png
       :alt: Console action create
       :width: 90%

    .. thumbnail:: /img/graphql/core/actions/example-transformation-2.png
       :alt: Console action create
       :width: 90%

  .. tab:: API

    Action definition:
    
    .. code-block:: graphql
    
      type Mutation {
        updateProfile(picture_url : String!) : ProfileOutput
      }
      
      type ProfileOutput {
        id: String!
        user_metadata: String!
      }
    
    The transform is given by:
    
    .. code-block:: json

      {
        "request_transform": {
          "body": "{\"user_metadata\": {\"picture\": {{$body.input.picture_url}} } }",
          "url": "{{$base_url}}/{{$session_variables['x-hasura-user-id']}}",
          "method": "PATCH"
        }
      }