Execute API (v4)

Execute multiple calculations from a Spark service.

Returns: Service execution response.

Each Spark service can be called to perform calculations by calling the Execute API. The v4 specification of the Execute API supports synchronous batching enabling multiple requests to be submitted at the same time. This API specification also forms the basis for using the Batch APIs and Introduction to XConnector.

This endpoint should not be used for very large number of input records because there is an execution time limit of 55 s and an error will be returned.

For very large numbers of input records, we recommend using applications that utilize the Batch APIs.

POST /{tenant}/api/v4/execute
POST /{tenant}/api/v4/public/execute

Authorization

• Bearer {token} accessible from Authorization - Bearer token or systematically via Client Credentials.

  • The request headers should include a key for Authorization with the value Bearer {token}.

• API key created from Authorization - API keys. The API key groups must contain User groups that are also assigned to Permissions - Features permissions Spark.SyncBatch.json or Spark.AllEncompassingProxy.json.

  • The request headers should include the keys x-synthetic-key and x-tenant-name with the values of the API key and tenant name respectively.

• No Authorization is required for Authorization - Public APIs.

Path parameters

Key	Value
tenant *	Tenant is part of your Log in to Spark URL and also available in the User menu.

Request body

Content-Type: application/json

Name	Description
inputs	See inputs definitions
service	URI or service_id of the service being called. Example 1: stocks/NVDA Example 2: stocks/NVDA[1.4.3] Example 3: stocks/NVDA[1.4] take the latest version starting with 1.4. Example 4: stocks/NVDA[1] take the latest version starting with 1. Example 5: /folders/stocks/services/NVDA Example 6: a5e3f03a-57ca-4889-adae-0630be54bd87
version_id	version_id of the requested service version. Example: 8183f03a-57ca-4889-adae-0630be54bd87
version_by_timestamp	Timestamp to resolve the service version for Manage service versions and effective dates. Use Timestamp Converter to convert dates to ISO 8601. When call to a service is made using a URI or service_id this is used to determine the latest version of a service which have effective start and effective end dates that bound version_by_timestamp. If omitted, the current date and time is used. If the version_by_timestamp does not fall within the effective start and effective end dates of any versions, then the response will be an error. When calling a specific version using version or version_id this field has no effect. Example: 2023-10-31T01:30:00.000-05:00
output	Array of strings to denote the outputs to keep in the results. The strings can also contain regular expressions. Example 1: ["value_*", "valuation_by_*"] Alternatively direct references to Excel ranges are possible. For Neuron 1.17.0 and later this can be enabled In Excel by adding a Named Range referenced to a cell called xBuildParams. The cell contents must contain '--direct_addressing=true. Example 2: ["@Sheet1!B2:D4"] Example 3: ["@MyNamedRange"] Furthermore if #SparkFormulaValueVector is added to these requests, only the calculated results would be returned.
compiler_type	Calculation engine for the request. By default this uses the setting defined in Change the Default Service Type. Note that Type3 is not supported with this version of the API specification. Example: Neuron or Xconnector
manual_now	Neuron behavior: Default behavior in Spark for the Excel NOW() and TODAY() functions are to return the value based upon server time. If a Unix epoch time is provided, then that will be used to derive the current time and date instead. Example: 1650593119 would represent 2024-10-29T02:44:48
call_purpose	Tag API Call. Can be queried in API Call History. Example: admin system p
correlation_id	Tag API Call. Can be queried in API Call History. Example: 456
source_system	Tag API Call. Can be queried in API Call History. Example: mycicd
subservice	Comma separated string of subservice names. Reference How to: Work with subservices. When this is not specified or set as #Default#, outputs not related to subservices are shown. Example 1: subservice1 will only show the the outputs from subservice1. Example 2: subservice1,subservice2 will only show the outputs from subservice1 and subservice2. Example 3: #Default#,subservice2 will show outputs not relating to subservices and from subservice2. Example 4: * all subservices will be included

inputs definitions

Refer to Execute API (v3) request_data for information about input definitions and data types.

Synchronous request of inputs using JSON objects

If using JSON objects, a synchronous request containing multiple records can be made by stacking the request objects together within the inputs array. The requests are formatted in a similar way to the Execute API (v3) request_data. The response will also be returned in a similar format, with outputs being an array of JSON objects corresponding to each record.

In this example, the service has 2 inputs: A is a single value and B is a 3x2 table comprising of the headers B1 and B2. This request includes 2 records for calculation.

{
    "inputs": [
        {
            "A": 1,
            "B": [
                {"B1": 6, "B2": 3},
                {"B1": 9, "B2": 4}
            ]
        },
        {
            "A": 7,
            "B": [
                {"B1": 0, "B2": 2}
            ]
        }
    ]
}

Synchronous request of inputs using JSON arrays

If using JSON arrays, a synchronous request containing multiple records can be defined in the following structure:

• The first row contains the name of the inputs in an array.

• The subsequent rows define the values for the corresponding records, in this case A and B. If an input is a table, its table headings are also included in the data, in this case B1 and B2 are repeated in each entry.

• This format is much more compact for large datasets and used for the Batch APIs and Introduction to XConnector.

• The response will also be returned in a similar format.

In this example, the service has 2 inputs: A is a single value and B is a 3x2 table comprising of the headers B1 and B2. This request includes 2 records for calculation.

{
    "inputs": [
        ["A", "B"],
        [1, 
            [
                ["B1", "B2"],
                [6, 3],
                [9, 4]
            ]
        ],
        [7,
            [
                ["B1", "B2"],
                [0, 2]
            ]
        ]
    ]
}

Parameters to resolve Spark service versions

Spark will use the parameters version_id, service, and version_by_timestamp in order to resolve down to the most appropriate version_id to use for an API call. Learn more about the version resolution in the section Manage service versions and effective dates.

version_id will be resolved by Spark the quickest.

Execute API will always resolve the version_id parameter first, service_id parameter second, and then service last. It is possible that these 3 may refer to different services entirely but Spark will resolve the reference in the same order.

Sample request

The 2 sample requests will give equivalent results with different JSON formatting.

• A11 is a single value.

• A33 is an input table with headers A1, A2, A3.

• A44 is an input table with headings A1, B (with subheadings B1, B2), and C1.

Array of JSON objects

Array of JSON arrays

{ "inputs": [ { "A11":10, "A33":[ {"A1":10,"A2":20,"A3":30}, {"A1":110,"A2":120,"A3":130} ], "A44":[ {"A1":10,"B.B1":20,"B.B2":30,"C1":40}, {"A1":110,"B.B1":120,"B.B2":130,"C1":140} ] }, { "A11":20, "A33":[ {"A1":20,"A2":40,"A3":60}, {"A1":220,"A2":240,"A3":260} ], "A44":[ {"A1":20,"B.B1":40,"B.B2":60,"C1":80}, {"A1":20,"B.B1":240,"B.B2":260,"C1":280} ] } ], "service": "MyFolder/BlockParty", "call_purpose": "Array of JSON objects" }

{ "inputs": [ ["A11","A33","A44"], [10, [ ["A1","A2","A3"], [10,20,30], [110,120,130] ], [ ["A1","B.B1","B.B2","C1"], [10,20,30,40], [110,120,130,140] ] ], [20, [ ["A1","A2","A3"], [20,40,60], [220,240,260] ], [ ["A1","B.B1","B.B2","C1"], [20,40,60,80], [220,240,260,280] ] ] ], "service": "MyFolder/BlockParty", "call_purpose": "Array of JSON arrays" }

Response body

Content-Type: application/json

Key	Value
outputs	Array of outputs. The elements of the array correspond to the input request records. Outputs will be formatted in a similar way to the inputs. The layout of outputs depends on whether the inputs comprised of an array of JSON objects or JSON arrays.
process_time	Array representing the time for Spark to process each record of the API call. The elements of the array correspond to the input request records. Example: [39, 24]
errors	Array of errors. The elements of the array correspond to the input request records. Reference response_data.
warnings	Array of warnings. The elements of the array correspond to the input request records. Reference response_data.
service_id	service_id of the resolved service. Example: 48a953cc-ed34-4454-b5c7-1141912f2f8d
version_id	version_id of the resolved service version. Example: 6bf49dca-5bc2-4144-9710-5988a0f44163
version	Resolved service version number. Example: 4.15.2
call_id	Universally unique identifier for this API Call. This can be referenced in the API Call History. Example: f6123393-d33f-4ff6-86a4-a663111afd82
compiler_version	Compiler version of this service version. Example: 4.15.2
correlation_id	Value from Request body.
request_timestamp	Request timestamp. Example: 2020-10-29T09:53:18.8314052Z

Sample response

HTTP 200 OK Content-Type: application/json

Array of JSON objects

Array of JSON arrays

{ "outputs": [ { "A11":20, "A33":[ {"A1":20,"A2":40,"A3":60}, {"A1":220,"A2":240,"A3":260} ], "A44":[ {"A1":20,"B.B1":40,"B.B2":60,"C1":80}, {"A1":220,"B.B1":240,"B.B2":260,"C1":280} ] }, { "A11":40, "A33":[ {"A1":40,"A2":80,"A3":120}, {"A1":440,"A2":480,"A3":520} ], "A44":[ {"A1":40,"B.B1":80,"B.B2":120,"C1":160}, {"A1":440,"B.B1":480,"B.B2":520,"C1":560} ] } ], "process_time": [1,1], "warnings": [null,null], "errors": [ [ { "source_path": "$.Input.A11", "error_category": "validation_error", "error_type": "error.VALIDATION", "message": "Input Not Valid", "additional_details": "BlockParty" } ], [ { "source_path": "$.Input.A11", "error_category": "validation_error", "error_type": "error.VALIDATION", "message": "Input Not Valid", "additional_details": "BlockParty" } ] ], "service_id": "daa1ed5f-6a41-43dd-99ff-20bceca73f81", "version_id": "f3849415-0d2d-44b8-afbd-aab27ce73b43", "version": "0.1.0", "call_id": "e0a71fd5-1589-4277-b74a-7ccdd39cd628", "compiler_version": "1.16.0", "correlation_id": null, "request_timestamp": "2024-03-12T02:52:45.531Z" }

{ "outputs": [ ["A11","A33","A44"], [20, [ ["A1","A2","A3"], [20,40,60], [220,240,260] ], [ ["A1","B.B1","B.B2","C1"], [20,40,60,80], [220,240,260,280] ] ], [40, [ ["A1","A2","A3"], [40,80,120], [440,480,520] ], [ ["A1","B.B1","B.B2","C1"], [40,80,120,160], [440,480,520,560] ] ] ], "process_time": [1,1], "warnings": [null,null], "errors": [ [ { "source_path": "$.Input.A11", "error_category": "validation_error", "error_type": "error.VALIDATION", "message": "Input Not Valid", "additional_details": "BlockParty" } ], [ { "source_path": "$.Input.A11", "error_category": "validation_error", "error_type": "error.VALIDATION", "message": "Input Not Valid", "additional_details": "BlockParty" } ] ], "service_id": "daa1ed5f-6a41-43dd-99ff-20bceca73f81", "version_id": "f3849415-0d2d-44b8-afbd-aab27ce73b43", "version": "0.1.0", "call_id": "bb4cf8fb-358e-4fc8-9a0b-19dbdb219e81", "compiler_version": "1.16.0", "correlation_id": null, "request_timestamp": "2024-03-12T05:14:37.912Z" }