Academy
Data Sources

API Rest Step

The API Rest step imports data from an API to start a data flow. An API (Application Programming Interface) is a set of rules and standards that allows different systems to communicate with each other. After configuring the step, you run the flow and use the data returned by the API. It is located in the Data Source category of the toolbar.

API Tab

Configure the main connection data here:

  • Name: identifies the step. The field is editable; set the name you prefer.

  • Endpoint URL: API access address.

  • Method: indicate if the API is GET or POST.

  • Has pagination?: enable when the API is paginated. When enabled, choose the Pagination Type.

When pagination exists, the type can be:

  • Paginated by page index: pages are controlled by page number (page 1, page 2, and so on). Enter the {page} variable in the URL where the page number goes. Example: https://minhaapi.com.br/relatorio?empresa=1&data=2023-08-02&pagina={page}.

  • Paginated by row index: pages are controlled by the number of rows. The request informs the start row and the row limit to return. Use the {offset} variable for the start row and {limit} for the record limit. Example: https://minhaapi.com.br/relatorio?empresa=1&data=2023-08-02&offset={offset}&limit={limit}.

Data sample: the sample generated in the API Rest step brings only the first page. The idea is to display some records that help build the flow.

What are GET and POST

GET and POST are HTTP methods that indicate the desired action in a request. Every request needs to specify a method. There are others (PUT, DELETE, among others), but the two used to obtain data are GET and POST:

  • GET: used when the goal is to obtain data.

  • POST: used mainly to send data and, in some cases, also to obtain it.

Método POST: when selecting POST, the platform enables the Body tab for you to fill in the data to be sent in the call.

URL Parameters

You can provide parameters to be replaced in the URL before connecting to the API. There are two types:

  • Fixed: filled with a fixed value, such as the company code or the desired currency.

  • Ref Date: sends the reference date of the flow execution. During flow editing, the simulation date (defined in the Data Sample bar) is used; during execution, the provided reference date is used.

Suppose you query data by providing the company and date in the URL. Instead of the fixed URL https://minhaapi.com.br/relatorio?empresa=1&data=2023-08-02, configure the endpoint with variables: https://minhaapi.com.br/relatorio?empresa={empresa}&data={data}. The parameters would be: empresa as Fixed with value 1, and data as Ref Date with format YYYY-MM-DD.

Authorization Options

When the API requires access authorization, register one of these types:

  • Basic Authorization: provide the access username and password.

  • AWS Signature: for APIs in the AWS (Amazon Web Services) environment. Fill in the AWS Access Key ID, AWS Secret Access Key, ServiceCode, and Region Code fields.

  • Bearer Token: provide the token.

  • Authentication Route: configures an API to obtain the access token, which is then used in the API that queries the data. Fill in the Parameter Key (name of the authentication parameter sent in the header during execution) and the Prefix (text added before the obtained value). Then, click Configure new route to define the API that obtains the token, selecting a field to use as the token. For example, if the return is a Bearer token, use Authorization as the key and Bearer as the prefix.

Header Tab

You can register header parameters, with the same two types available in the URL:

  • Fixed: filled with a fixed value, such as the company code or the desired currency.

  • Ref Date: sends the execution reference date. During flow editing, the simulation date is used; during execution, the provided reference date is used.

Body Tab

Available when the method is POST. Configure:

  • Content type: specify the body format. The options are JSON (application/json), XML (application/xml), and XML (text/xml).

  • Body Parameters: register request body parameters, in the Fixed (fixed value) or Ref Date (execution reference date) types.

Variables are declared in the body within curly braces. For example, to send company and date, the body would be { "codigoempresa": "{empresa}", "datacompetencia": "{data}" }, with the parameters empresa as Fixed (value 1) and data as Ref Date (format YYYY-MM-DD).

Return Tab

Define here which API fields will be used as output columns (mandatory step).

  1. Execute Connection: click to execute the API call.

  2. Configure columns: after the connection, the platform displays the list of available fields. The icons indicate the field type:

  • Icon #: index field, displayed when there is a list of data.

  • Icon @: field returned by the API.

  • Icon { }: a list of data.

  1. Select the fields you want to use. Each selected field enters the list below with Source (field source in the data tree), Column Name, Sample (first value found), and Data Type (identified type). When the type is Date, select the date format next to it.

  2. Save: saves the settings. To exit without saving and return to the Designer, use Close.

  • Transform SQL Step

  • Dattos IA Step

Was this helpful?