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.

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.

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.

An example from Mailerlite app:

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

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:

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

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.

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:

"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)

Last updated