Validation APIs

Review Prerequisites for dynamic validation before continuing with this section.

## Depending on the desired reference parameter, different URI are available.

# Standard implementation
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

# Neuron implementation - known to have issues and not recommended for use
POST /{tenant}/api/v3/folders/{folder}/services/{service}/validation-inputs
POST /{tenant}/api/v3/service/{serviceId}/validation-inputs
POST /{tenant}/api/v3/version/{versionId}/validation-inputs

This API is an extension of the Execute API (v3) that returns the data validation assigned to single value Xinput within a Spark service.

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
tenant *	Tenant is part of your sign-in 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.

An additional Execute API 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 exactly the same as a validation that contains formulas. For example, 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, for example 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 in 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 is important when defining the workbook.

Validation API Dynamic.xlsx

21KB

Open

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

1. Upload this service to Spark.

2. Call the API externally.

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

validation_type static

Get all of the static single value Xinput data validation.

Sample request body

• Empty request_data and request_meta to extract the default_values validation.

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

Sample response

• 01_letter is validation_type static.

• 02_number is validation_type dynamic.

• 02_number is a dependent_input of 01_letter.

HTTP 200 OK Content-Type: application/json

{
    "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": {
        ...
    },
    "error": null
}

validation_type dynamic part 1

Get the updated data validation for 02_number after an input change.

Sample request body

• 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.

HTTP 200 OK Content-Type: application/json

{
    "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": {
        ...
    },
    "error": null
}

validation_type dynamic part 2

Check whether 01_letter to b and 02_number to 23 are valid after the input change.

Sample request body

• 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.

HTTP 200 OK Content-Type: application/json

{
    "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": {
        ...
    },
    "error": null
}