REST API

Creating a connector

To create a REST API connector, follow the steps below.

  1. Access the Connector Manager screen from the left-side menu or by clicking the card in the Welcome screen.

  2. Click + NEW CONNECTOR at the top right of the screen.

  3. Select the REST API connector’s card.

  4. Import a file with the Open API 3.0.0 specification.

    When you click the connector’s card, a modal window will open to import the file. Click SELECT FILE to locate it and then click IMPORT.

    You can only import local files with the following extensions:

    • json;

    • yaml;

    • yml.

    When you import the file, the system will check if there are structure errors and if the file is according to the supported version.

    After validating it, the connector’s configuration screen will open and its fields will be filled in automatically with the imported data.

  5. If you want to change the information automatically loaded, edit the fields:

    • Name: Connector’s name

    • Version: Connector’s version

    • Description: Connector’s description

    • Add icon: Option to add an icon to represent the connector in the Flow.

  6. Select the endpoints of the Open API 3.0.0 that you want to use in the connector.

    Click Select All to select all the available endpoints.

    To the right of the endpoints, you will see the request and response of each selected endpoint.

  7. Click CREATE.

create rest api connector
You cannot edit a REST API connector.

Configuring a connector

After creating the connector, you have to configure it in the Flow screen. To do that, follow the steps below:

Adding the connector to the canvas

  1. Access the Integration Flows screen and select the integration flow.
    If you want to create a new one, click + NEW FLOW and access the Flow screen.

    Check out our tutorial about how to create your first integration flow.

  2. Click the hub icon with plus sign icon in the editing menu on the left.

  3. Select the connector you want. You can use the search bar search steps icon to find it.

  4. Click the edit icon pencil icon to configure the form.

Each step allows only one connection to the previous step and one connection to the next step.

To copy the step, click the copy icon button. If the step form is already configured, the settings will be copied too.

To delete the connector from the canvas, select it and click the trashcan icon button.

Configuring the form

Next, follow the REST API Connector’s form sections and learn how to configure them:


Information and Requirements

These two sections contain the following fields and buttons:

  • Name: name of the connector. You can edit this field.

  • Connector: blocked field that only identifies the connector.

  • Route: select the HTTP method and the path to be used by the connector. You can also type the HTTP method or the path to filter the results.

  • URL: enter the URL that will make the request.

  • Request Timeout: enter the request timeout in milliseconds. By default, the timeout is 3000 milliseconds and the maximum value is 300000 ms.

    By clicking the Properties icon list icon on the right of the URL and Request Timeout fields, you can:
    a. Filter and display environment variables and the payload from previous steps (if the steps are connected) to be used to configure the form.
    b. Create expressions using the Expression Builder.

  • Security: automatically enables the type of security configured on the Authorizations screen. If there is more than one type of security configured, the field will show a list with the options. In case the connector doesn’t have any type of security enabled, by default the field will show the No Auth option.

  • Ignore Errors button: by default, this button is disabled and you can enable it. Check more details about the function of Ignore Errors on the table below:

    Enabled switch

    Disabled switch off

    Execution continues, even if there are errors in the process.

    Execution will be stopped immediately.

    The logs show the step with an error.

    The logs show the execution up to the step with the error.

    The following steps will be executed.

    No further step will be executed.
connector form



Body

To configure your payload using the Body tab, you have two options:

body connector


Data Mapping

With Data Mapping, you can map your data manually, choosing which data you want to map and transform.

To do this, follow the steps below:

  1. Click + CREATE DATA MAPPING.

    After clicking the button, a new screen will open:

    dataMapping

  2. In FROM, select one or more attributes to map and transform. Ex: "First_name" and "Last_name". This section shows the data from the previous steps as well as the environment variables.

  3. In TO, select just one attribute. Ex: "Name". In the image above, the attributes "First_name" and "Last_name" will be transformed into "Name". This section shows the properties related to the payload’s body.

  4. In EXPRESSION, you see the attributes selected in FROM and TO columns. If you want to create the expression manually, enter the input attributes or create an expression by clicking the fx-button button on the right. Only the Concat function is currently available and there is no character limit.

  5. Click the ADD MAPPING button to register the mapping made.

    You can repeat the above steps as many times as necessary.

  6. In DATA MAPPING FIELDS, check the data mapping. Each row shows the input attribute (or expression) and the output attribute in the respective columns.

    A gray arrow between the FROM/TO columns indicates the absence of an expression.

    To delete a row, select it and click on trashcan icon to the right of the section name.

  7. Click CONFIRM to save the data mapping.

Once saved, you will be able to view it under the Body tab and the editing option will be enabled.


Data Mapping with Full Body

In the top right-hand corner of Data Mapping, you can enable or disable the FULL BODY button. This way, the connector request is sent with the properties, structures and values in the call request and you do not need to map them one by one. By enabling the button, you automate the entire data mapping process.

full body

To automate the process, follow the steps below:

  1. Toggle on the FULL BODY button.

  2. In the Input Data field, select the step to apply the data mapping. The complete body of the selected step will be included in the REST API Connector request. You will see the request and response data from the connectors and the request data from the trigger.

  3. In Full Data Mapping, view the mapping done automatically by transforming the FROM fields into TO fields.

  4. Click CONFIRM to save the data mapping.

Once saved, you will be able to view it under the Body tab and the editing option will be enabled.



By clicking the Header tab, you will see the headers of the request associated with the Route chosen when configuring the REST API Connector form.

Configure the following mandatory fields:

  • Name: by default, the form loads the header name automatically. If no header is associated with your connector route, you can enter the name manually.

  • Value: enter the value of the header. You can do this manually or by using the expression icon button to access the Expression Builder. In this case, you can create expressions or simply use the Properties column there to select the attributes and click CONFIRM.

To add more values, click on plus sign icon.
To delete the value, click on trashcan icon.
header connector



Query

By clicking the Query tab, you will see the queries of the request associated with the Route chosen when configuring the REST API Connector form.

Configure the following mandatory fields:

  • Name: by default, the form loads the query name automatically. If no query is associated with your connector route, you can enter the name manually.

  • Value: enter the value of the query. You can do this manually or by using the expression icon button to access the Expression Builder. In this case, you can create expressions or simply use the Properties column there to select the attributes and click CONFIRM.

To add more values, click on plus sign icon.
To delete the value, click on trashcan icon.
query connector



Path

By clicking the Path tab, you will see the paths of the request associated with the Route chosen when configuring the REST API Connector form.

Configure the following mandatory fields:

  • Name: by default, the form loads the path name automatically. If no path is associated with your connector route, the fill is blocked.

  • Value: enter the value of the path. You can do this manually or by using the expression icon button to access the Expression Builder. In this case, you can create expressions or simply use the Properties column there to select the attributes and click CONFIRM.

path connector

Once you have finished configuring the connector, click SAVE.

Expression Builder

The Expression Builder component allows you to create expressions with parameters and variables through functions and conditions available within the component. This allows you to adjust the expressions to meet your needs.

You can create expressions for the following fields:

  • URL;

  • Request Timeout.

Follow the steps below to access the Expression Builder screen:

  1. Click the Properties icon list icon, to the right of the URL or Request Timeout fields.

  2. Next, click the expression icon icon in the upper-right corner.

expression builder connector

The Expression Builder screen contains the following sections:

  • Properties: shows data from previous steps and from the environment variables. Filter the attributes using the search field at the top of the section and then click the magnifying glass icon. You can select more than one attribute. When selected, the attribute will appear in the Expression field.

  • Expression: field to enter the input attributes or to create an expression by clicking the fx button button on the right. Only the Concat function is available to create the expression.

When selecting two or more attributes in the Properties field, you must create an expression.

To save the information, click CONFIRM. To exit the screen and cancel the operation, click X, at the top right.

Alert icon

After configuring the step connector, click SAVE.

You will see an alert icon alertIcon on the step connector in case the fields below are not configured:

  • Route

  • URL

  • Request Timeout

  • Security

You will also see the alert if:
- variables from Environment Variables or
- attributes from previous steps
were changed or deleted while they are still being used in the configured step.
Thanks for your feedback!
EDIT

Share your suggestions with us!
Click here and then [+ Submit idea]