REST API

Creating a connector

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

Access the Connector Manager screen
Click + NEW CONNECTOR
Select the REST API connector’s card
Import a file with the Open API 3.0.0 specification
- In the modal window that will open, click SELECT FILE to locate the file.
- After locating the file, click IMPORT.
- 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 validation, the connector configuration screen will open, with all fields automatically filled with the imported data.
  
  You can only import files with the json, yaml and yml extensions.
Edit the connector’s information fields (optional)
- Name: connector’s name.
- Version: connector’s version.
- Description: connector’s description.
- Add icon: add an icon to represent the connector.
Select the routes
- If you prefer, click Select All to select all the available routes.
  
  You can view the request and response of each selected route next to the routes' list.
Click CREATE

It is not possible to edit a REST API connector. If you wish to make changes, such as selecting a new route, you will need to create a new connector. For other modifications, update the specification in the import file.

Configuring a connector

To use the connector you created in the Connector Manager in an integration, you have to configure it in the Flow screen. To do that, follow the steps below:

Add the connector to the canvas

Access the Integration Flows screen
Select your integration flow
- If the integration flow that will use the connector already exists, select it and open the Flow screen.
- If you want to use the connector in a new flow, click + NEW FLOW.
  
  Check out our tutorial about how to create your first integration flow.
Select the connector in the editing menu on the canvas
- Click the icon in the editing menu on the left.
- Search for and select the connector you registered. You can use the search bar to find it.
- Select the connector on the canvas and click the editing icon to open the configuration form.
- Make sure the connector is connected to the previous and following steps on the canvas.

Each connector allows only one input connection and one output connection.

When you select the connector on the canvas, you can:

Edit it .
Copy it icon. If the connector’s form is already configured, the settings will be copied too.
Delete it icon.

Fill in the configuration form

Name: name of the connector. Loads automatically the name you used during the creation of the connector, but it can be edited.
Connector: blocked field that shows the name of the connector at the time of its creation.
Route: select the route (example: GET/customer) the connector will use. If there are many, you can type the HTTP method or the path to filter the results.
URL: enter the URL that will make the request. If you registered the URL in the environment variables, you can click the icon on the right and select it.

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

By clicking the Properties icon on the right of the URL and Request Timeout fields, you can:

Filter and display environment variables and the payload from previous steps (if the steps are connected) to be used to configure the form.
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: ignores erros during the flow’s execution. By default, this button is disabled and you can enable it. Check more details about it on the table below:

Enabled

Disabled

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.

Configure the tabs: Body, Header, Query and Path

Body

To configure the request body, click + CREATE DATA MAPPING.

There are two ways of configuring:

Data Mapping or
Data Mapping with Full Body.

Data Mapping

Data mapping is essential for integrating different systems and applications, allowing for the seamless exchange of information between them. It transforms data from one format to another, adjusting fields and types as needed.

Using the "FROM" and "TO" columns, you can manually map your data:

FROM: indicates the source of the data, which includes previous steps and registered environment variables.
TO: represents the destination of the data, corresponding to the body of the connector’s request.

1 to 1 data mapping

Select an attribute in the "FROM" column on, the left.
Select an attribute from the "TO" column on, the right.
Click on ADD MAPPING.
Click on CONFIRM.
You can repeat the above steps as many times as necessary.

Once saved, you will be able to view the data mapping in the Body tab, and the edit option will be enabled.

See a demonstration in the GIF below:

2 to 1 or more data mapping

For 2 to 1 or more data mapping, you will need to use an expression.

Before selecting attributes in the "FROM" column, click on the concat function (the only available function) in the EXPRESSION section. Alternatively, you can write the expression manually.

You can only select one attribute from the "TO" column, and that attribute cannot be chosen more than once.

See a demonstration GIF below:

Now, here’s another example of data mapping:

Using the concat function to map three attributes from the "FROM" column (logradouro, município, and UF) to the logradouro attribute in the "TO" column.
Mapping the nome_social attribute from the "FROM" column to the nome attribute in the "TO" column. The For Each appears in front of the expression, as it is the source of the payload.
Manually mapping the city "São Paulo" to the cidade attribute in the "TO" column.

See the examples in the GIF below:

Data mapping fields

You can view the data mapping in DATA MAPPING FIELDS.
Each row presents the input attribute (or the expression) and the output attribute in their respective columns.

If the arrow between the "FROM" and "TO" columns is gray, it indicates that there is no associated expression. Conversely, if the arrow is orange, it means an expression has been used.

To delete a row from the data mapping:

Click on the arrow between the "FROM" and "TO" columns to select the row.
Then click on the next to the title of the "DATA MAPPING FIELDS" section.

Attributes structure

Consider the data mapping example with the concat function:

concat($.API_Brasil.Response.Payload.logradouro$.API_Brasil.Response.Payload.municipio$.API_Brasil.Response.Payload.uf) ->  $.Request.Payload.endereço.logradouro

Input attributes

Note how the different parts of the API’s data structure appear in the data mapping:

Response
- Payload
  - Logradouro
  - Município
  - UF
    
    concat($.API_Brasil.Response.Payload.logradouro$.API_Brasil.Response.Payload.municipio$.API_Brasil.Response.Payload.uf)
    
    concat: the concat function joins the three elements into a single string.
    
    $.: a common convention in programming languages and data structures that use path notation to access elements within objects or JSON.
    
    API_Brasil.Response.Payload.logradouro: this path points to the "logradouro" field within the payload of the API Brasil response.
    
    API_Brasil.Response.Payload.município: this path points to the "município" field within the payload of the API Brasil response.
    
    API_Brasil.Response.Payload.uf: this path points to the "uf" field within the payload of the API Brasil response.

Output attribute

Request
- Payload
  - Endereço
    
    Logradouro
    
    $.Request.Payload.endereço.logradouro

This snippet indicates that the result of the concatenation (the full address) will be stored in the "logradouro" field of the request payload.

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:

Toggle on the FULL BODY button.
In the Input Data field, select the step to apply the data mapping. You can select the connector’s request/response payload, the trigger’s request payload or For Each.
In Full Data Mapping, view the mapping done automatically by transforming the "FROM" fields into "TO" fields.
Click CONFIRM to save the data mapping.

Once saved, you will be able to view it under the Body tab and the edit 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 fields:

Name: by default, the form loads the header name automatically. If there is none, you can enter the name manually.
Value: enter the value of the header. You can do this manually or by using the 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.

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 fields:

Name: by default, the form loads the query name automatically. If there is none, you can enter the name manually.
Value: enter the value of the query. You can do this manually or by using the 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

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 fields:

Name: by default, the form loads the path name automatically. If there is none, the field is blocked.
Value: enter the value of the path. You can do this manually or by using the 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.

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:

Click the Properties icon , to the right of the URL or Request Timeout fields.
Next, click the 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 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 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

You will see an alert icon on the connector if:

The fields below are not configured:
- Route
- URL
- Request Timeout
- Security
The environment variables you registered are changed or deleted.
The attributes defined in previous steps have been modified or removed 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]