Connection

Modified on Sun, Mar 19, 2023 at 10:16 PM

APIs generally employ authentication or authorization mechanisms to control access to their endpoints.

The inMultifamily platform provides a selection of the most commonly used connection types, each with pre-populated code. You only need to adjust the code to cater to your unique needs and the API's specifications.

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

We have covered the basics of creating a simple module.

Now, let's explore how to modify our search module to accommodate a unique API token for every user.

Navigate to the Connections tab, where you'll likely see an empty list of your connections.

Click the large button featuring a plus sign and select "Create a new Connection."

A dialog box will appear, allowing you to name your connection and designate its type. Fill out the dialog as demonstrated and click "Save."

Upon creating the new Connection, it will be displayed in the list.

Select the newly created Connection, which will bring up a page featuring two tabs: COMMUNICATION and PARAMETERS.

The pre-configured communication will resemble the following:

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

The COMMUNICATION section outlines a basic request to verify if the user-provided credentials are valid. The prevalent method for credential validation involves calling an endpoint to obtain the user's information and/or tokens, if applicable. The majority of APIs feature 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.

Code:

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

Communication code:

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

Paramaters:

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

Take note of the directive concerning the sanitization of API tokens. To prevent any leakage of personal tokens or keys, it is essential to consistently apply sanitization.  Remember to employ sanitization in both base and connection aspects!

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

A dialog for attaching a connection will appear. In this dialog, choose the connection you recently created.

While configuring a connection, don't overlook the base component! Recall that the base should encompass all elements shared by every module and remote procedure, such as baseUrl, authorization, sanitization, error handling, etc. To make adjustments, click on the BASE tab and modify the code as needed:

Hence, click the BASE tab and make the necessary adjustments to 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.

Great job! You've now learned how to create a new connection, associate it with an existing module, and map the connection data in the base. It's the perfect moment to learn about error handling.