Adding Input Validations to an API Module

While front-end validation improves the user experience by providing instant feedback, it shouldn't be relied upon as the sole line of defense for data quality or protection. Browser-side UI can be bypassed, manipulated, or simulated using API tools. Adding input validation to your API modules ensures that the backend only processes safe, well-formed, and expected data. This protects the quality and stability of your application.

This article covers example strategies for implementing server-side input validation in Unqork API modules.

Note: Module configuration falls under Application Security in the shared security responsibility model. You are responsible for designing and building your applications securely. Consult your internal security experts to determine the appropriate validation approach for your use case. Learn more about input validation at the OWASP Input Validation Cheat Sheet.

Recommendations

Always validate inputs in your server-side module. You cannot rely on the UI to pass valid inputs because the request can be modified between the client and server. Validate any inputs received from the client before using them. This is especially important when the module has Act as super-user when server-side executing enabled.

Server-side input validation works together with error handling. Consider how you will generate error messages and return them to the caller when an invalid input is received.

In the examples in this article, the module defaults to an error state at the beginning of execution. Any failure to validate an input results in the module returning an error.

Considerations

The right validation approach depends on your application's requirements. Use the following questions to help guide your decisions.

Who are the end-users of your application?

• Is the module restricted to internal end-users only, or is it open to the public?

How is each field used in the module?

• A field intended to store a number might receive a string without visible issues if the value is only displayed. The unexpected type will cause failures if the value is used in downstream calculations.

How sensitive is the data?

• Unqork IDs and personally identifiable information (PII) require stricter validation than less sensitive fields.

How is the data used and where does it go?

• Does the field fire an action? An invalid value might fire the wrong action.

• Does the data reach downstream reporting systems where data cleanliness matters?

Do you have a downstream system with its own validation requirements?

• If a downstream system requires a minimum character length on a field, add the same check in your module to surface issues earlier.

What is the risk if the field receives an invalid value?

• The higher the risk, the more validation to apply. If an invalid ID can  unintended actions, add extra controls for that field.

The right approach depends on your application's use cases and requirements. Use these questions as a starting point, not a checklist.

Strategies

The following sections describe four example strategies for adding input validation to a server-side execute module.

Data Type Validation

Check that inputs match the expected data type. For example, confirm that a field is a number instead of a string, or that its length falls in an expected range. This approach can protect both data quality and system security.

For example, a module that receives a withdrawAmount input could use =LODASH('isNumber',A) to confirm the value is numeric before passing it to downstream processing.

REGEX Validation

Use a regular expression to check an input against a specific pattern. Many tools are available for building and testing regular expressions, like regex101.com.

For example, if a module accepts a submissionId input, you can validate that the value matches the expected Unqork ID format. Unqork IDs are 24-character hexadecimal values. The pattern for this format is:

^[0-9a-f]{24}$

This same pattern applies to other Unqork-specific IDs, like module IDs or workflow IDs.

Allowlist Validation

Check inputs against a defined list of acceptable values (sometimes called an allowlist, static list, or ENUM). This follows the principle of least privilege: a value is rejected unless it is explicitly permitted.

For example, store the allowlist in a Data Collection and query it at runtime to check whether the input matches an allowed value. This is similar to a drop-down component in a UI module, which restricts values to a preset list of options.

Custom Business Rules

Validate inputs against rules specific to your business logic.

For example, if a record with a status of closed must also have a dateClosed value populated, consider adding this check in your API module. Even if the UI enforces this rule, validating it server-side can protect against cases where the API is called directly, bypassing the UI entirely.

Example Configuration

The following examples demonstrate each strategy using POC modules. Select each module link to open the configuration in the Unqork Training environment.

Data Type Validation

Module: Input Validation for Numeric Data Type

This example validates that a withdrawAmount input is a number greater than zero. Downstream logic only proceeds if the input is valid.

1. The Initializer component sets a default sse['httpResponseCode'] of 500 and triggers the dwfCheckIsValid Data Workflow component.

2. The dwfCheckIsValid Data Workflow component runs two formulas against the withdrawAmount input:

   • =IF(LODASH('isNumber',A),TRUE,FALSE), which checks that the value is numeric

   • =IF(AND(A=TRUE,_arg>0),TRUE,FALSE), which checks that the value is greater than zero

   The output is written to withdrawAmountValidType as true or false. On completion, it triggers the ruleCheckInputValid Decisions component.

3. The ruleCheckInputValid Decisions component reads withdrawAmountValidType and sets the response:

   • false → sse['httpResponseCode'] = 400, response body: "withdrawAmount is required to be a numeric data type."

   • true → sse['httpResponseCode'] = 200

REGEX Validation

Module: Input Validation Using REGEX

This example validates that a moduleId input matches the expected Unqork ID syntax before the module runs further logic.

1. The Initializer component sets a default sse['httpResponseCode'] of 500 and triggers the calcIfInputIsValid Calculator component.

2. The calcIfInputIsValid Calculator component runs the formula =IFREGEXMATCH(A, "^[0-9a-f]{24}$","yes","no") against the moduleId input and writes the result to moduleIdValid.

3. A Decisions component evaluates the result and responds as follows:

   • moduleIdValid = no → sse['httpResponseCode'] = 400, response body: "Invalid moduleId provided."

   • moduleIdValid = yes → triggers a Plug-In component to execute the provided moduleId

Allowlist Validation

Module: Input Validation Using an Allowlist

This example checks that a moduleId input appears in a pre-approved list stored in a Data Collection.

1. The Initializer component sets a default sse['httpResponseCode'] of 500 and triggers the plugGetValidModuleIdList Plug-In component.

2. The plugGetValidModuleIdList Plug-In component returns the list of valid module IDs. A Data Workflow component filters the list against the provided moduleId and outputs yes or no to moduleIdValid.

3. A Decisions component evaluates moduleIdValid:

   • no → sse['httpResponseCode'] = 400, response body: "Invalid moduleId provided."

   • yes → triggers a Plug-In component to execute the provided moduleId

Custom Business Rules

Module: Input Validation Using Custom Business Rules

This example validates a status field against an allowlist and enforces a conditional requirement: when status = 'closed', the dateClosed field must be populated. Valid status values are new, inProgress, and closed.

1. The Initializer component defaults sse['httpResponseCode'] to 500 and triggers the plugGetAllowList Plug-In component to retrieve valid status values from a Data Collection.

2. Once plugGetAllowList resolves, a Data Workflow component (dwfValidateInputs) performs the following:

   • Checks that the provided status value is in the allowlist

   • When status = 'closed', checks that dateClosed is populated

   • Based on the result, triggers either the ruleHTTPResponses Decisions component (sets sse['httpResponseCode'] to 400 and returns "request failed") or the plugCreateSubmission Plug-In component