Get support

Processing of input parameters

Mapping all parameters

{
    ...
    "body": {
        "firstName": "{{parameters.firstName}}",
        "lastName": "{{parameters.lastName}}",
        "email": "{{parameters.email}}"
    },
    // ... other directives
}

Notice, that you have to map every single parameter correctly.

There is a risk of a typo or omission of a parameter.

Using an IML function or omitting a parameter

Sometimes, you don't want to map all parameters in the body for some reason:

  • the parameter shouldn't be sent at all (technical parameters such as selects, etc.)

  • the parameter should be sent somewhere else than in the body, e.g. in the url

  • the parameter has to be wrapped in an IML or custom IML function

{
    "url": "/contact/{{parameters.id}}",
    "method": "PUT",
    "body": {
        "email": "{{parameters.email}}",
        "firstName": "{{parameters.firstName}}",
        "lastName": "{{parameters.lastName}}",
        "registrationDate": "{{formatDate(parameters.registrationDate, 'YYYY-MM-DD')}}"
        
    },
    // ...
}

Notice, that you have to map every single parameter correctly.

There is a risk of a typo or omission of a parameter.

Handling arrays, nulls, and empty strings

Make and other third-party services transport values in many different formats. It is important to know how to handle the value types of arrays, nulls, and empty strings.

Bad practices

{
    "url": "/messages.json",
    "method": "POST",
    "body": {
        "status": "active",
        "content": "{{ifempty(parameters.content, undefined)}}"
    },
    // ...
}

It isn't possible to send a null value to a service.

{
    "url": "/messages.json",
    "method": "POST",
    "body": {
        "status": "active",
        "content": "{{if(parameters.content, parameters.content, undefined)}}"
    },
    // ...
}

It isn't possible to send a null, empty string, and 0 (zero) value to a service.

Let users decide what parameters they want to send to the service. Make has a feature to show how to process values. This feature allows users to define exactly how Make should behave when the value is "empty". For example, if a user defines that they want to send a specific field to a service even if the value is null , empty string, or an empty array, it will be sent to the service. In module communication, config passes parameters without any modification.

Date parameters

When a field is a type "date", it should be possible to use our keyword "now" as a value, which means, the field should accept ISO-8601 date format and if the service requires only the date (no time) or a different format like timestamp, this formatting should happen inside the module.

Users of the app should never be prompted to format the date inputs the way API requires! Such apps will not be approved by Make.

Communication:

{
    "url": "/api/users",
    "method": "POST",
    "body": {
        "name": "{{parameters.name}}",
        "birthday": "{{formatDate(parameters.birthday, 'YYYY-MM-DD')}}",
        "due_date": "{{formatDate(parameters.due_date, 'X')}}"
    },
    "response": {
        "output": "{{body}}"
    }
}

Parameter birthday is required to have format YYYY-MM-DD and parameter due_date is required to be a timestamp by the service, so the formatting happens inside the Communication part of the module.

Parameters:

[
    {
        "name": "name",
        "type": "text",
        "label": "Name"
    },
    {
        "name": "birthday",
        "type": "date",
        "label": "Birthday"
    },
    {
        "name": "due_date",
        "type": "date",
        "label": "Due Date"
    }
]

The parameters birthday and due_date are correctly date typed and don't need to be formatted by the user, he can freely work with now keyword.

Query String (QS)

Query string parameters should be defined using the qs directive as a key-value collection, where the key is the parameter name and the value is the parameter value. Values in the qs collection are automatically encoded, so you do not need to escape them manually.

Note: The same automatic encoding applies to the headers and body collections for request headers and body payloads, respectively.

Example:

{
    "url": "http://yourservice.com/api/items",
    "qs": {
        "limit": 100,
        "since": "{{parameters.since}}",
        "until": "{{parameters.until}}"
    }
    // ... other directives
}

This will issue the request to URL like:

http://yourservice.com/api/items?limit=100&since=2023-01-01&until=2023-01-31

Note: If you provide a query string directly in the url directive, it will not be automatically encoded. You have to encode it manually. But in common cases, the entering query string in url is not recommended approach, especially when values are inserted dynamically. See below section for the details.

Special case: Query string parameters in the URL

In most cases, the query string in URL is not the best practice. It is better to use the qs collection, but sometimes there is a special usecase when you need to use the query string directly in the URL.

The main difference is that the query string in the URL is not encoded automatically, so you have to do it manually. This can be useful when the 3rd-party service requires a very specific format or encoding of the query string parameters. In that case you can add query string directly to the url directive string and manage the encoding yourself.

Example of specific query string parameters in the URL:

{
    "url": "http://yourservice.com/api/users/{{parameters.userId}}?groups=(1,2,3,4)&specificallyEncodedParameter={{parameters.specific}}",
    // qs: {} // <- Do not include the `qs` collection here
    "method": "POST",
    // ...
}

The most common use case for this is when 3rd-party service requires special symbols like brackets [] or parentheses () to be unencoded in the query string.

Important: Never mix the qs directive together with the query string in the URL. This will lead to invalid escaping of parameters specified in the url.

Using arrays in qs

You can also use an array as a value in the qs collection. In this case, the resulting query string will repeat the key for each value in the array, e.g. ?tag=one&tag=two&tag=three.

Example:

{
    "url": "http://yourservice.com/api/items",
    "qs": {
        "anytag": ["one", "two", "three"]
    }
}

This will issue the request to URL like:

http://yourservice.com/api/items?anytag=one&anytag=two&anytag=three

Using structured data in qs

NOTE: qs (and also headers) are single-level collections only, meaning that you cannot specify nested collection in their parameters:

Incorrect structure example:

{
    "qs": {
        "someProp": {
            "anotherOne": { // <- Collection in Collection is NOT allowed like this
                "and-one-more": "THIS WILL NOT WORK"
            }
        }
    }
}

The example above will not work.

Because there is no defined standard for how to encode nested objects in query string, you need to implement it manually based on special requirements of 3rd party service. There can be couple of possible approaches, but the most common one is to use dot notation for nested properties. This means that you can use a dot . to separate the keys in the query string.

Example of dot notation:

Correct structure example:

{
    "qs": {
        "someProp.anotherOne.and-one-more": "THIS WILL WORK"
    }
}

This will issue the request with the query string:

?someProp.anotherOne.and-one-more=THIS%20WILL%20WORK
PreviousMappable parametersNextProcessing of output parameters

Last updated