Connection

APIs usually employ some sort of authentication/authorization to limit access to their endpoints.

Make platform provides you with a list of the most used types of connections while in every each there is a code prefilled. You only need to edit it up to your and/or API's needs.

Create a new Connection panel

Mostly, you will need to change the URLs and names of the parameters.

Setting up a connection for our demo API

While the /helloworld endpoint was accessible without any authentication/authorization, the other endpoints of the Demo API will require an API key.

Let’s try to call endpoint /books that should respond with a list of books in the library:

http://demo-api.integrokit.com/api/v1/books

Without providing the API key, the response will contain the following error:

{"error":"Invalid or missing API key"}

To enable the user of your Module to specify her/his own API key (assuming each user has got her/his own API key to access the API), you need to create a Connection.

We have covered the basics of creating a simple module. Since the /books endpoint will always return an array with items, you will need to create a new module type Search. Now, let’s see how to update our search module with a variable API token for each user.

Click the tab Connections. The (probably still empty) list of all your connections will be shown. Click the large button with the plus sign and choose Create a new Connection. A dialog will pop up, where you can name your connection and choose its type. Fill the dialog as shown and click Save.

A New Connection Dialog

The new Connection will appear in the list. Click the new Connection. A page with two tabs will be shown: COMMUNICATION and PARAMETERS.

A pre-configured communication will look like this:

{
    "url": "https://www.example.com/api/whoami",
    "headers": {
        "x-api-key": "{{parameters.apiKey}}"
    },
    "log": {
        "sanitize": ["request.headers.x-api-key"]
    }
}

The COMMUNICATION section specifies a simple request to determine whether the credentials entered by the user are valid or not. The most common way to validate the credentials is to call an endpoint to get the user’s information and/or tokens, if available. Most of the APIs have such an endpoint.

There are types of connections, e. g. API Key, which don't have such an endpoint. In this case, it is recommended to call an endpoint, which will work in every case, and if possible will return the account's data, e. g. an endpoint /about or /me, etc.

Not only the credentials entered by the user will be validated, but also the account's name or email can be stored in the name of the connection (the value in brackets after the user's connection name), see the example below.

Occurence in a scenario

Example of Connection's Name

Code

...
"response": {
    "metadata": {
            "type": "email",
            "value": "{{body.data.user.email}}"
        }
},
...

Since our Demo API doesn't have any suitable endpoint, we will not use any.

The code should be as below:

Communication

{
    "headers": {
    "api-token": "{{parameters.apiKey}}"
        },
    "log": {
        "sanitize": ["request.headers.api-token"]
    }
}

Parameters

[
    {
        "name": "apiKey",
        "type": "password",
        "label": "API Key",
        "required": true,
        "editable": true
    }
]

Note that we used sanitization for API tokens. Always sanitize personal information, like tokens, keys and authentication secrets so they are not visible to other people.

Always use sanitization in base and connection! Learn more about sanitization here.

Also note the password type of the apiKey parameter. The password type hides the content of the apiKey field when the app users create or edit the connection.

You can read more about the password parameter type here.

Once you finish the connection configuration, you can go back to your search module and click Attach Connection.

Attach Connection

An Attach Connection dialog will appear. There, select the currently created connection.

Selection of Connection

When we are setting up a connection, we should not forget about the base!

As you remember, in base, there should be everything common to all modules and remote procedures, e. g. baseUrl, authorization, sanitization, error handling, etc.

Therefore, click BASE tab and edit the code:

{
    "baseUrl": "http://demo-api.integrokit.com/api/v1",
    "headers": {
        "api-token": "{{connection.apiKey}}"
    },
    "log": {
    "sanitize": ["request.headers.api-token"]
    }
}

Notice that not only we added a new header with authorization (we mapped the apiKey from connection), but also edited the sanitization.

Awesome! You just learned how to add a new connection, attach it to an existing module, and map the connection data in base. Now, it is the right time to learn, how to make error handling, continue below.