Base

The Base section should contain data that is common to all (or most) requests. At the very least, this should include the root URL, the authorization headers, the error-handling section, and the sanitization.

Right

{
    "baseUrl": "https://www.example.com/api/v1",
    "headers": {
        "Authorization": "Bearer {{connection.accessToken}}"
    },
    "response": {
        "error": {
            "message": "[{{statusCode}}] {{body.error.message}} (error code: {{body.error.code}})"
        }
    },
    "log": {
        "sanitize": [
            "request.headers.authorization"
        ]
    }
}

Wrong

Base URL

Base URL

Make sure that the Base URL uses the URL of the API, which is shared among all modules or their majority.

In case of a request for approval of your app by Make, make sure that the base URL is a production endpoint with a domain that belongs to the app itself.

Apps with development or staging URLs, or apps with a domain belonging to a cloud computing service, will not be approved!

When the service has a different domain for each user, the domain should be asked for in the connection and then the value should be used in the Base tab.

Right

An example from Mailerlite app:

{
    "baseUrl": "https://api.mailerlite.com/api/v2"
}

Right (Different Domain)

An example from Freshsales app:

{
    "baseUrl": "https://{{connection.domain}}.freshsales.io"
}

Wrong (Different Domain)

{
    "baseUrl": "https://mydomain.freshsales.io"
}

The "mydomain" should be a variable used from the Connection.

Wrong (app will not be approved)

{
    "baseUrl": "https://mailerlite.heroku.com/development"
}

Authorization and sanitization

AuthorizationSanitization

The Base section should also have authorization, which is common for all modules. This authorization should use the API Key, Access Token, or Username and Password entered in the connection. The sanitization should hide all these sensitive parameters.

Examples of possible authorization and sanitization:

API Key

{
...
    "headers": {
        "Authorization": "Token {{connection.apiKey}}"
    },
    "log": {
        "sanitize": [
            "request.headers.authorization"
        ]
    }
...
}

Access Token

{
...
    "qs": {
        "access_token": "{{connection.accessToken}}"
    },
    "log": {
        "sanitize": [
            "request.qs.access_token"
        ]
    }
...
}

Basic auth

{
...
    "headers": {
        "authorization": "Basic {{base64(connection.username + ':' + connection.password)}}"
    },
    "log": {
        "sanitize": [
            "request.headers.authorization"
        ]
    }
...    
}

Secret in request body

{
...
    "body": "There is something {{parameters.secret}} hidden here.",
    "type": "raw",
    "log": {
        "sanitize": [
            "request.body<parameters.secret>"
        ]
    }
...
}

Error handling

Each service sends an error message when an error occurs. This most of the time happens when the request has wrong parameters or values or when the service has an outage. That's why error handling is required.

In case of a request for approval of your app by Make, make sure error handling is correctly implemented!

Error handling

The error handling code should correspond to the structure of the server response. Let's assume that the JSON response has the following format in the cases where something goes wrong:

{
    "error": {
        "code": "E101",
        "message": "The company with the given ID does not exist."
    }
}

Here's how the error section should (and should not) look:

Right

"response": {
    "error": {
        "message": "[{{statusCode}}] {{body.error.message}} (error code: {{body.error.code}})"
    }
}

The error object in our example contains the code and message fields. It is also important to show the status code of the error, this can be accessed using the statusCode keyword. So in the case of HTTP error 400, the error message could look like this:

[400] The company with the given ID does not exist. (error code: E101)

Wrong

"response": {
    "error": {
        "message": "{{body.error.text}}"
    }
}

The error object in our example contains the code and message fields, but not a text field.