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

.. meta::
   :description: Transform actions requests
   :keywords: hasura, docs, action, transform

.. _action_transforms:

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

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

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

Transforms are used to perform transformations on the HTTP
request generated by an action.

.. 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"
        }
      }