REST

Naming Convention

As we want to keep the naming of the Universal Modules the same across all Apps which support them, the Universal Module should keep the following guidelines.

Module label: Make an API Call

Module description: Performs an arbitrary authorized API call.

Example of creation of a new universal module for Make app

URL Parameter

Expected input from users should start with / (for example /tasks) so users can copy-paste the endpoint path from the service documentation.

If the API has multiple versions of API available, the user should be allowed to use any of them. The URL set in the Universal module should end before the version.

Set the correct URL in the "help" and add a working endpoint example.

Good Practice

Communication

{
    "url": "https://www.example.com/{{parameters.url}}"
}

Mappable parameters

{
        "name": "url",
        "type": "text",
        "label": "URL",
        "help": "Enter a path relative to `https://www.example.com`. For example: `/v1/something`",
        "required": true
}

Even when the URL in Communication ends with / before {{parameters.url}} we ask users to use / in the URL because it is automatically removed.

Bad Practice

Communication

{
    "url": "https://www.example.com/v1/{{parameters.url}}"
}

Mappable parameters

{
        "name": "url",
        "type": "text",
        "label": "URL",
        "help": "Enter a path relative to `https://www.example.com/v1/`. For example: `something`",
        "required": true
}

The "url" in the Communication has API version in it.

The "help" has misleading example, the base url should end without slash and version and the example start with slash and version.

Example:

Appearance

Example of universal module

Communication

{
	"qs": {
		"{{...}}": "{{toCollection(parameters.qs, 'key', 'value')}}"
	},
	"url": "https://www.example.com/{{parameters.url}}",
	"body": "{{parameters.body}}",
	"type": "text",
	"method": "{{parameters.method}}",
	"headers": {
		"{{...}}": "{{toCollection(parameters.headers, 'key', 'value')}}"
	},
	"response": {
		"output": {
			"body": "{{body}}",
			"headers": "{{headers}}",
			"statusCode": "{{statusCode}}"
		}
	}
}

Static parameters

[]

Mappable parameters

[
	{
		"help": "Enter a path relative to `https://www.example.com`.\nFor example: `/v1/api/list`",
		"name": "url",
		"type": "text",
		"label": "URL",
		"required": true
	},
	{
		"name": "method",
		"type": "select",
		"label": "Method",
		"default": "GET",
		"options": [
			{
				"label": "GET",
				"value": "GET"
			},
			{
				"label": "POST",
				"value": "POST"
			},
			{
				"label": "PUT",
				"value": "PUT"
			},
			{
				"label": "PATCH",
				"value": "PATCH"
			},
			{
				"label": "DELETE",
				"value": "DELETE"
			}
		],
		"required": true
	},
	{
		"help": "You don't have to add authorization headers; we already did that for you.",
		"name": "headers",
		"spec": [
			{
				"name": "key",
				"type": "text",
				"label": "Key"
			},
			{
				"name": "value",
				"type": "text",
				"label": "Value"
			}
		],
		"type": "array",
		"label": "Headers",
		"default": [
			{
				"key": "Content-Type",
				"value": "application/json"
			}
		]
	},
	{
		"name": "qs",
		"spec": [
			{
				"name": "key",
				"type": "text",
				"label": "Key"
			},
			{
				"name": "value",
				"type": "text",
				"label": "Value"
			}
		],
		"type": "array",
		"label": "Query String"
	},
	{
		"name": "body",
		"type": "any",
		"label": "Body"
	}
]

Interface

[
	{
		"name": "body",
		"type": "any",
		"label": "Body"
	},
	{
		"name": "headers",
		"type": "collection",
		"label": "Headers"
	},
	{
		"name": "statusCode",
		"type": "number",
		"label": "Status code"
	}
]

Samples

{}

OAuth Scopes

When your app requires specifying scopes to access different groups of endpoints, you need to tweak the connection code a bit to make it work correctly with the Universal Module. Here's how:

Step 1

Add a new advanced parameter called scopes to the connection parameters.

Preview

Advanced Parameter Scopes

Code

[
    {
        "name": "clientId",
        "type": "text",
        "label": "Client ID",
        "advanced": true
    },
    {
        "name": "clientSecret",
        "type": "text",
        "label": "Client Secret",
        "advanced": true
    },
    {
        "name": "scopes",
        "label": "Additional Scopes",
        "type": "array",
        "help": "Use this to get an access to extra scopes.",
        "advanced": true
    }
]

Step 2

In the authorize part of the connection, merge the original scopes with additional scopes added by the parameter from the previous step.

Preview

Scope Parameter in Authorization

Code

"authorize": {
        "qs": {
            "scope": "{{join(distinct(merge(oauth.scope, ifempty(parameters.scopes, emptyarray))), ',')}}",
            "client_id": "{{common.clientId}}",
            "redirect_uri": "{{oauth.redirectUri}}",
            "response_type": "code"
        },
        "url": "...",
        "response": {
            "temp": {
                "code": "{{query.code}}"
            }
        }
}

Step 3

Now when you want to use Universal Module with scopes that have not been granted to the connection previously, you can create a new connection and request those additional scopes manually.

Example of connection with additional scopes