INPUT REST API

The INPUT REST API operator allows you to call any service available via the REST, receive the data returned by that service, and place it onto the data bus either in text or bit form. To learn more about converting text data into data bus bits, see the CONVERT FORMAT TO BITS operator.

The INPUT REST API operator is executed once at the beginning of the data bus and initiates its operation by retrieving data independently of any previous records.

The operator configuration allows you to:

specify the REST service URL and the HTTP method (GET, POST, etc.),
dynamically set headers and query parameters,
handle various authorization mechanisms,
and control the format of the received data.

This operator makes it possible to automatically load data from external systems into the GRAVITY environment and begin further processing within the project.

EXAMPLE PROCESS USING THE OPERATOR

The process assumes that the Status Code returned by the called service will be checked manually.

OUTPUT DATA BUS CONFIGURATION

When using the INPUT REST API operator, its output data bus will contain a single record built from the data field returned by the service (typically JSON, but it may also be XML or plain text) and—depending on the configuration—Error checking fields containing the returned Status Code of the service execution.

On the Execution tab, you must configure how the operator behaves after receiving a response from the called service.

New column with result → Name of the output data bus column (bit) that will receive the data returned by the Web Service.
Error checking → Defines how the operator behaves when it receives a Status Code indicating that the service execution failed.

Report an error when Status Code is invalid → In the case of an invalid Status Code, the process is stopped, and the error message from the Body field with an error message field is displayed.
Send Status Code on the busbar → In this case, the process will not be stopped. The Status Code is passed to the data bus in the bit whose name is specified in New column with Status Code, and it can be evaluated in the process using the IF operator. If the service returns error details, they are available in the New column with result field.

Body field with an error message → The error message used when the process is automatically stopped due to receiving an invalid Status Code.
New column with Status Code → The column (bit) into which the execution Status Code will be placed.

The Single execution and Result target fields are inactive here and are only used in the

REST API CALL operator.

SERVICE ADDRESS CONFIGURATION

To configure the connection to the service, go to the Request tab and enter the HTTP method used by the service, the address at which the service is available, and—if required—the authorization method.

The operator supports the following HTTP methods:

GET
POST
PUT
DELETE
PATCH

and the following basic authorization methods:

Basic Auth
Api key
Simple auth
Bearer token
Bearer token (system connections)

Because the operator provides full access to construct HTTP request headers and allows them to be built dynamically using parameters, you can use virtually any authentication system.

When specifying the service address in the Endpoint you can use project parameters or global parameters. You can insert them by clicking the button next to the field, or by typing @ for local parameters and {{ for global parameters.

You can provide the call parameters directly in the Endpoint field in the format [endpoint]?parName1=value&parName2=value, or enter them as name → pairs on the Query parameters tab.

HTTP REQUEST HEADERS

The Headers tab allows you to view, add, and modify HTTP request headers. The operator automatically sets several standard headers.

If you want to modify any header, double-click its value to edit it.

To add a new header, click the last record and enter the header name and value.

In a header, you can insert:

the value of a project parameter by prefixing its name with @ , e.g. @username.
the value of a global parameter by enclosing it in double curly braces, {{[globalVariableName]}} , for example:{{userName}}
the value of a data bus bit (only in the REST API CALL operator) by surrounding its name with percent signs. Format: %bitName%, example: %userName%.

REQUEST CONTENT

On the Body tab, you can configure the content sent in the request to the REST service.

The operator allows you to send data in various formats, depending on the requirements of the external service:

none - Sends no content in the request body.
form-data - Sends data as key/value pairs without encoding. This type also allows binary data to be sent.

After selecting this type, you can add additional fields by clicking the empty record and entering the key name and value.

x-www-form-urlencoded – Data is sent as key/value pairs, but encoded in the same way as URL parameters. Binary data cannot be sent using this format.

Fields are defined the same way as in form-data — by clicking the empty record.

raw – In this mode, you can enter any text string as the request body. You must also specify the format, which allows the system to set the appropriate Content-Type.

Available formats:

Text – plain text
JavaScript – JavaScript code
JSON – data in JSON (JavaScript Object Notation) format
HTML – data in HTML (HyperText Markup Language) format
XML – data in XML (Extensible Markup Language) format

Depending on the selected format, the system will automatically set the appropriate Content-Type header in the request.