Validation API

We strongly recommend reviewing Prerequisites for dynamic validation before continuing with this section.

Returns: Input validation parameters.

## Depending on the desired reference parameter, different URI are available.
POST /{tenant}/api/v3/folders/{folder}/services/{service}/validation
POST /{tenant}/api/v3/service/{serviceId}/validation
POST /{tenant}/api/v3/version/{versionId}/validation
POST /{tenant}/api/v3/public/folders/{folder}/services/{service}/validation
POST /{tenant}/api/v3/public/service/{version}/validation
POST /{tenant}/api/v3/public/version/{versionId}/validation

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 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
environment *	Environment is part of your Log in to Spark URL.
tenant *	Tenant is part of your Log in to Spark URL and also available in the User menu.
folder *	Folder associated with the request.
service *	Service associated with the request.
serviceId *	service_id of the requested service. The latest service version will be referenced.
versionId *	version_id of the requested service version.

Request body

Content-Type: application/json

Follows from Execute API (v3) Request body.

There is one additional parameter in the Execute API that controls whether the static or dynamic validations are returned. When a service is uploaded to Spark, the validations based upon the default values are saved into a validation file. This eliminates the need for Spark to process the validations on every single API call.

Key	Value
request_meta.validation_type	default_values returns the pre-processed validations that are static or dynamic (see below for more information). If no parameter is provided, the default_values will be returned. dynamic returns the updated validations for the validations identified as dynamic based upon the request_data. This only returns the validations that are different than those stored in the validation file.

Response body

Content-Type: application/json

Follows from Execute API (v3) Response body. For each input the API will also return the properties of the validation as an output.

Key	Value
validation_type	dynamic the definition of the validation in this cell changes depending on another input. This is not the exactly same as a validation that contains formulas, e.g. if a validation range is linked to static numbers, it would not be considered as dynamic. static validation in this cell does not depend on another input.
dependent_inputs	List of input fields that would be impacted by this particular validation. For example, if Age and Gender are used to determine the Products that can be offered, then for the validation of Age and Gender, Products would be included as a dependent input. null if no dependent inputs.
validation_allow	Relates to Excel Data Validation allow format types, e.g. Decimal, List, Date.
ignore_blank	Shows TRUE or FALSE depending on the value of the Excel Data Validation Ignore blank checkbox. Excel Ignore blank is an unusual feature. When this is FALSE it does not mean the value entered of the cell cannot be blank.
min	Minimum value for an input, null if no min validation. If this is a dynamic validation field, this will store the initial validation based upon the default values.
max	Maximum value for a numeric input, null if no max validation. If this is a dynamic validation field, this will store the initial validation based upon the default values.
options	Enumerated list of the validations, null if no enumerated validation. If this is a dynamic validation field, this will store the initial validation based upon the default values.

Sample file

In this example, the choice of 01_letter from list_a affects the valid list of 02_number from list_b. Note that the choice of default values are important when defining the workbook.

21KB

Validation API Dynamic.xlsx

Open

To use this example file you will need to do the following:

1. Upload this service to Spark.

2. Call the API externally, for example using Postman.

3. Modify the API URI following a valid URI. In most cases, modifying the existing endpoint URI from /execute to /validation should work.

validation_type static

Sample request

• Empty request_data and request_meta to extract the default_values validation.

{
  "request_data": {},
  "request_meta": {}
}

Sample response

• 01_number is validation_type static.

• 02_number is validation_type dynamic.

• 02_number is a dependent_input of 01_letter.

{
    "status": "Success",
    "response_data": {
        "outputs": {
            "01_letter": {
                "validation_allow": "List",
                "validation_type": "static",
                "dependent_inputs": [
                    "02_number"
                ],
                "min": null,
                "max": null,
                "options": [
                    "a",
                    "b"
                ],
                "ignore_blank": true
            },
            "02_number": {
                "validation_allow": "List",
                "validation_type": "dynamic",
                "dependent_inputs": null,
                "min": null,
                "max": null,
                "options": [
                    "1",
                    "2"
                ],
                "ignore_blank": true
            }
        },
        "warnings": null,
        "errors": null,
        "service_chain": null
    },
    "response_meta": {
        "service_id": "f9c4fc11-9112-4abf-b75a-cd0579e313ac",
        "version_id": "70c60d67-590d-4805-8c40-c5870e6161fb",
        "version": "1.0.0",
        "process_time": 0,
        "call_id": "2aebf898-09df-49d9-8a0b-935c7486fb9d",
        "compiler_type": "Type3",
        "compiler_version": "1.0.0",
        "source_hash": null,
        "engine_id": "9AE2AFFB74E404D221C7DDF3AC11CEF7",
        "correlation_id": null,
        "parameterset_version_id": null,
        "system": "SPARK",
        "request_timestamp": "2022-10-03T12:09:14.392Z"
    },
    "error": null
}

validation_type dynamic part 1

Please also reference Prerequisites for dynamic validation.

Sample request

• Set 01_letter to b and validation_type to dynamic.

{
  "request_data": {
    "inputs": {
      "01_letter": "b"
    }
  },
  "request_meta": {
      "validation_type": "dynamic"
  }
}

Sample response

• The updated validation for 02_number is returned.

• Note the response has an error because no value for 02_number was submitted.

• Therefore the default value in the spreadsheet of 02_number = 1 was used which led to a validation error.

{
    "status": "Success",
    "response_data": {
        "outputs": {
            "02_number": {
                "validation_allow": "List",
                "validation_type": "dynamic",
                "dependent_inputs": null,
                "min": null,
                "max": null,
                "options": [
                    "23",
                    "24",
                    "25",
                    "26"
                ],
                "ignore_blank": true
            }
        },
        "warnings": null,
        "errors": [
            {
                "error_category": "validation_error",
                "error_type": "error.VALIDATION",
                "additional_details": null,
                "source_path": "$.Input.02_number",
                "message": "Input must be one of: 23, 24, 25, 26"
            }
        ],
        "service_chain": null
    },
    "response_meta": {
        "service_id": "f9c4fc11-9112-4abf-b75a-cd0579e313ac",
        "version_id": "70c60d67-590d-4805-8c40-c5870e6161fb",
        "version": "1.0.0",
        "process_time": 0,
        "call_id": "b392cf0d-8acf-4bf6-9d7b-2c1a15d0b509",
        "compiler_type": "Type3",
        "compiler_version": "1.0.0",
        "source_hash": null,
        "engine_id": "9AE2AFFB74E404D221C7DDF3AC11CEF7",
        "correlation_id": null,
        "parameterset_version_id": null,
        "system": "SPARK",
        "request_timestamp": "2022-10-04T12:50:55.145Z"
    },
    "error": null
}

validation_type dynamic part 2

Sample request

• Set 01_letter to b and 02_number to 23 and validation_type to dynamic.

{
  "request_data": {
    "inputs": {
      "01_letter": "b",
      "02_number": 23
    }
  },
  "request_meta": {
      "validation_type": "dynamic"
  }
}

Sample response

• The updated validation for 02_number is returned without errors.

{
    "status": "Success",
    "response_data": {
        "outputs": {
            "02_number": {
                "validation_allow": "List",
                "validation_type": "dynamic",
                "dependent_inputs": null,
                "min": null,
                "max": null,
                "options": [
                    "23",
                    "24",
                    "25",
                    "26"
                ],
                "ignore_blank": true
            }
        },
        "warnings": null,
        "errors": null,
        "service_chain": null
    },
    "response_meta": {
        "service_id": "f9c4fc11-9112-4abf-b75a-cd0579e313ac",
        "version_id": "70c60d67-590d-4805-8c40-c5870e6161fb",
        "version": "1.0.0",
        "process_time": 0,
        "call_id": "c7739cf5-7297-48f9-a3c5-a13b5e7aa1f6",
        "compiler_type": "Type3",
        "compiler_version": "1.0.0",
        "source_hash": null,
        "engine_id": "9AE2AFFB74E404D221C7DDF3AC11CEF7",
        "correlation_id": null,
        "parameterset_version_id": null,
        "system": "SPARK",
        "request_timestamp": "2022-10-04T12:54:08.742Z"
    },
    "error": null
}