# Create Mini-Apps

TIP

an email verification API, mailboxlayer (opens new window) will be used as an example for how to create and edit a Mini-App.

mini-app

To create an App, follow steps:

  1. "Integration"
  2. "My Apps": apps created by you.
  3. "Create New App"
  4. name the App
  5. "Create"
  6. "Edit"

mini-app

On the editing page,

  1. later if you need to change the App name, make it here
  2. give a description
  3. add a logo
  4. finish the configuration, taking "Sample Data" for examples. See details below
  5. "Save"

# Auth

This block is for setting authentications of your App.

# Parameters

Name Data Type Description
type enum Supported value: APIKEY
params array Values required from users when installing e.g. API key
request object Send requests with parameters (e.g. email, api_key) and map the response to params (e.g. token)
connection object List of request headers or parameters

# Email Verification Example

mini-app

This is an authentication example with an API key in the query. As follow is how it will look like after users install the App:

mini-app

The "api key" set by users will then be stored in the variable "token".

# Other Examples

Example 1: APIKEY Auth, headers

{
    "type": "APIKEY",
    "params": [
        {
            "name": "token",
            "title": "Enter your api key:"
        }
    ],
    "connection": {
        "headers": {
            "Authorization": "Bearer [[token]]"
        }
    }
}

The "headers" in the "connection" will be added to each request, so you don't need to repeat it everywhere later.

Example 2: APIKEY Auth, query parameters

{
    "type": "APIKEY",
    "params": [
        {
            "name": "api_key",
            "title": "Enter your api key:"
        }
    ],
    "connection": {
        "qs": {
            "key": "[[api_key]]"
        }
    }
}

Same as above, the query string will be added to each request.

Example 3: APIKEY Auth, JWT token

{
    "type": "APIKEY",
    "params": [
        {
            "name": "email",
            "title": "Enter your email:"
        },
        {
            "name": "api_key",
            "title": "Enter your api key:"
        }
    ],
    "request": {
        "url": "https://example.com/get-token",
        "method": "POST",
        "body_format": "form",
        "cache": 3600,      //cache this request for 3600 seconds
        "payload": {
            "email": "[[email]]",
            "api_key": "[[api_key]]"
        },
        "mapping": [
            {
                "name": "token",
                "path": "$.data.token"
            }
        ]
    },
    "connection": {
        "headers": {
            "Authorization": "Bearer [[token]]"
        }
    }
}

The email and api_key provided by users will be sent as a request. Then the responses will be mapped to variable token by JSON path $.data.token. After that, it's used as a variable [[token]] in an authorization header. Again, the header will be added to each request later.

# Triggers

COMING SOON ...

# Actions

Actions are what functions/features users can do with your App. For example, this "Google Translate" App has 2 actions, "Detect Language" and "Translating text":

mini-app

In the coding area, you need to set the default information of the action, including name, title, description, forms and requests to make the action work in the flow with configuration.

At the bottom, click "Get product" for GET request example, and "Update product" for POST request example. The type of forms and requests are objects, therefore it needs to set several attributes.

# Parameters

Name Data Type Description
name string Identify the action, must be unique
title string Action title shown when using the app
description string Action description shown when using the app
forms array List of form objects for action configuration
requests array List of request objects to be performed in succession

# Form Object

Name Data Type Description
name string Field name, used as an identifier and variable inside request
type enum Value type, used for validation, supported values: string, number and select
title string Field title, displayed in UI
default string Default value for this field, If specified, the field becomes optional
source string Name of the source in Sources block, only for type=select

# Request Object

Name Data Type Description
url string Request URL
method enum HTTP request method, supported values: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
headers array List of request headers in key value pair, e.g. {"Content-Type": "application/json"}
payload json Request body
body_format enum Request body format, supported values: json, query, form, multipart, raw
mapping array Set of fields for request results mapping into custom fields

# Mapping Object

Name Data Type Description
name string Field name, used as identifier
type enum Field type, supported values: text, number, boolean, date, datetime, array
title array Field name, displayed in UI
path string String in a JSON path format

# Email Verification Example

As follow is the coding for the "Email Verification" App and the UI in Action steps.

Code:

mini-app

App UI:

mini-app

mini-app

# Other Examples

Example 1:

{
    "url": "https://translation.googleapis.com/language/translate/v2/detect",
    "method": "POST",
    "headers": {
        "Content-Type": "application/json"
    },
    "payload": {
        "q": "[[q]]"
    },
    "mapping": [
        {
            "name": "language",
            "type": "text",
            "title": "Detected Language",
            "path": "$.data.detections.0.0.language"
        }
    ]
}

Example 2:

{
    "url": "https://example/api/auth",
    "method": "POST",
    "body_format": "form",
    "cache": 3600,
    "payload": {
        "email": "[[email]]",
        "api_key": "[[api_key]]"
    },
    "mapping": [
        {
            "name": "token",
            "type": "text",
            "title": "Token",
            "path": "$.data.token"
        }
    ]
}

# Sources

Sources block is used to provide users with a list of options for the form value. Use the name of the source in the form parameter in the Actions block to build the connection.

There are 2 sources formats, static and dynamic. The options from a static source are fixed while a dynamic source brings changing options according to inputs.

Note

sources block is optional, depending on the type of form objects in the Actions block.

# Parameters

Name Data Type Description
name string Identify the variable
type enum Source type, supported values: enum:rpc, enum:static
list array List of fixed options shown when using the App. Only for type=enum:static
request object Request object when the source is dynamic. Only for type=enum:rpc

# Mapping Object in the Request Object

Name Data Type Description
type enum Field type, supported value: select
path string String in a JSON path format, for response data array
value string String in a JSON path format based on the path results. This is the real value returned when a label selected
label string String in a JSON path format based on the path results. Displayed in the drop-down list as label

# Examples

Forms in Actions block:

"forms": [
            {
                "name": "static_options",
                "type": "select",
                "title": "Static Options",
                "source": "product_type_list"
            },
            {
                "name": "dynamic_options",
                "type": "select",
                "title": "Dynamic Options",
                "source": "users_list"
            }
        ]

Sources block:

[
    {
        "name": "product_type_list",
        "type": "enum:static",
        "list": [
            {
                "value": "food",
                "label": "Food & Drink"
            },
            {
                "value": "toy",
                "label": "Toys"
            },
            {
                "value": "phone",
                "label": "Mobile Phone"
            }
        ]
    },
    {
        "name": "users_list",
        "type": "enum:rpc",
        "request": {
            "url": "https://jsonplaceholder.typicode.com/users",
            "method": "GET",
            "headers": {
                "Content-Type": "application/json"
            },
            "mapping": [
                {
                    "type": "select",
                    "path": "$",
                    "value": "$.id",
                    "label": "$.username"
                }
            ]
        }
    }
]

TIP

the request object in dynamic sources has been explained in Action block, check parameters details of the request object.

App UI:

mini-app

mini-app

Finally, click "Save" to finish the creation. Congrats!! You've just made a Mini-App successfully.💯💯

Last Updated: 4/26/2021, 10:45:51 AM