API_CALL

In Data access

This function requires a separate subscription and is not available in all Valsight instances.

The API_CALL function sends node values to an external service over an HTTP POST request and returns the service’s response to the model as a node.

Use this function when a calculation must run on an external system and the result should flow back into the model: API_CALL("https://example.com/sum", ['Node A', 'Node B'], ["Year", "Country"]).

Parameters

urlStringRequired

The endpoint the POST request is sent to. Must match the allow-list configured by an administrator (see Availability & limits).

inputNodesList of node referencesRequired

List of nodes, in square brackets, whose values are sent with the request.

resultLevelsList of level namesRequired

List of levels, in square brackets, that Valsight expects back from the service. These define the shape of the returned node.

formatStringOptional

Data format of the response. Only JSON is supported. Default: JSON.

versionStringOptional

Version identifier sent with the request.

messageStringOptional

Free-text message sent with the request.

timeoutNumberOptional

Time limit for the call, in seconds. If the service does not respond in time, the request is cancelled.

Output shape

Dimensionality

The levels listed in resultLevels.

Values

Taken from the service’s response, parsed from the Valsight Table JSON payload.

Row count

Determined by the rows the service returns.

Watch out

Availability & limits

API_CALL is off by default and is controlled by global feature flags that an administrator configures:

• featureFlags.apiCall.allowedUrlsRegex: a Java regular expression of permitted URLs. Empty by default, which allows no URLs, so an administrator must set it before the function can be used.
• featureFlags.apiCall.maxRowsToSend: maximum combined number of rows across the input nodes per request. Default 150000.
• featureFlags.apiCall.maxMbsToReturn: maximum response size read, in megabytes. Default 24.

Response format

Valsight validates a known set of keys in the response and ignores any others:

• response_status: SUCCESS or ERROR. On ERROR, Valsight displays the message in error_msg.
• output: the returned node, in the Valsight Table JSON structure.

An example response:

{
  "format": "JSON",
  "version": "1",
  "function_name" : "simple_plus",
  "response_status": "SUCCESS",
  "warning_msg": "",
  "error_msg": "",
  "output" : {
        "version": "1",
        "columnMetadata": [
            {
                "name": "Year",
                "columnType": "level",
                "levelId": 1
            },
            {
                "name": "measure",
                "columnType": "measure"
            }
        ],
        "rowData": [
            ["2015","50"],
            ["2016","100"],
            ["2017","150"],
            ["2018","200"]
        ]
    }
}

Example

This example sends two nodes to a service that adds them and returns the sum per Year and Country.

Input node: 'A'

Input node: 'B'

Formula: API_CALL("https://externalServer.com/sumTwoNodes", ['Node A', 'Node B'], ["Year", "Country"])

Valsight sends nodes A and B and requests the levels Year and Country back. When the service responds successfully, the result is:

See also

DATA

When the external data is already uploaded as a data table, reference it directly instead of calling a live service.