Processing of input parameters

Mapping all parameters

Bad practice

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

In this example you have to map every parameter correctly.

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

Good practice

Mappable parameters

Using an IML function or omitting a parameter

Sometimes, you don't want to map all parameters in the body. Some reasons may include:

• 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.

Bad practice

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

In this example you have to map every parameter correctly.

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

Good practice

Mappable parameters

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

Omitting of null or empty string parameters

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

Omitting of empty arrays

Let users decide which 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.

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 don't need to escape them manually.

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 in this way:

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

If you provide a query string directly in the url directive, it won't be automatically encoded. You have to encode it manually. But in common cases, entering the query string in the url is not a recommended approach, especially when values are inserted dynamically. See the Special case: Query string parameters in the URL section for more details.

Special case: Query string parameters in the URL

In most cases, having the query string in the URL is not the best practice. It is better to use the qs collection, but sometimes there may be a special case 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 third-party service requires a very specific format or encoding of the query string parameters. In that case, you can add a query string directly to the url directive string and manage the encoding yourself.

Example of specific query string parameters in the URL:

Example

{
    "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 a third-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 in this way:

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

Using structured data in qs

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

Incorrect structure example

{
    "qs": {
        "person": {
            "address": {
                "street": "123 Main Street"
            }
        }
    }
}

This example will not work.

Since there is no defined standard for how to encode nested objects in a query string, you need to implement it manually based on special requirements of the third-party service. The most common approach is to use dot notation (use a . to separate the keys in the query string) for nested properties.

Correct structure example