Request Validation

Overview

Request validation allows verifying if data passed to API is according to the schema that has been defined in API (or default schema if schema is not provided in API definition). This is useful when you want to make sure that the request data (body, headers, query params and path params) is the same as defined in the API definition so to ensure the integrity of data for the end client and elimination of errors that might occur if the request data wouldn't meet the expectations.

Validating form files

It is possible to validate files sent to ACE as multipart/form-data using request validation step. Validation is limited to verifying if the document node is a file and whether it is provided (if field is marked as required). Both single and array fields can be validated.

To specify some schema property as file, the property has to have type: string and format: binary or format: base64. Example:

Sample request body schema

title: My schema for validating file and text fields
type: object
properties:
  textField:
    type: string
  fileField:
    type: string
    format: binary
  filesArrayField:
    type: array
    items:
      type: string
      format: binary
required:
  - textField
  - fileField
  - filesArrayField

Configuration

• Request schema - schema definition for the doc node.
  • Requires schema to be set up first in ACE's schemas section. Afterwards the needed schema has to be selected under this selector. This is the default schema that will be used if dynamic API request associated with the flow has not a schema defined (and is also useful for testing the flow with debugger or test tool).
• Add header parameters to doc - add defined header parameters to the doc object.
• Convert request parameters (in doc) to schema types - converts request parameters (in doc) to the corresponding types defined in the schema.
• throw as error - if checked(default), failed schema validation will throw an error.
• target path - doc node on which to store the validation result when throw as error unchecked(empty array if successful, error object if failed).

Examples

Example schema

{
  "title": "loginRequestSchema",
  "nodeKey": "loginRequestSchema",
  "properties": {
    "username": {
      "type": "string"
    },
    "password": {
      "type": "string"
    }
  },
  "type": "object",
  "required": ["username", "password"]
}

Step configuration

stepType: request-validation
config:
  defaultSchema: loginRequestSchema
name: Request Validation
description: ""
condition: ""

Example flow with valid input data

    tags:
      - general
    steps:
      - stepType: request-validation
        config:
          defaultSchema: loginRequestSchema
        name: Request Validation
        description: ""
        condition: ""
      - stepType: jsonata
        config:
          maps:
            - mergeArrayItems: {}
              jsonata: "['data']"
              targetPath: result
        name: JSONATA Map
        description: ""
        condition: ""
    sampleInputSchema: loginRequestSchema
    sampleData:
      username: testUser
      password: test Pass

Flow result

{
  "doc": {
    "username": "testUser",
    "password": "test Pass",
    "result": ["data"]
  },
  "errors": [],
  "performance": {
    "steps": [
      {
        "step": "request-validation",
        "executionTime": 27
      },
      {
        "step": "jsonata",
        "executionTime": 0
      }
    ],
    "executionTimeOfFlow": 32,
    "timeMetric": "ms"
  }
}

Example flow with invalid ( password not passed ) input data

    tags:
      - general
    steps:
      - stepType: request-validation
        config:
          defaultSchema: loginRequestSchema
        name: Request Validation
        description: ""
        condition: ""
      - stepType: jsonata
        config:
          maps:
            - mergeArrayItems: {}
              jsonata: "['data']"
              targetPath: result
        name: JSONATA Map
        description: ""
        condition: ""
    sampleInputSchema: loginRequestSchema
    sampleData:
      username: testUser

Flow result

{
  "doc": {
    "username": "testUser",
    "result": ["data"]
  },
  "errors": [
    {
      "error": "Error in flow 'loginRequestInvalid' : Request Schema validation error",
      "validationErrors": [
        {
          "keyword": "required",
          "dataPath": "",
          "schemaPath": "#/required",
          "params": {
            "missingProperty": "password"
          },
          "message": "should have required property 'password'"
        }
      ]
    }
  ],
  "performance": {
    "steps": [
      {
        "step": "request-validation",
        "executionTime": 14
      },
      {
        "step": "jsonata",
        "executionTime": 1
      }
    ],
    "executionTimeOfFlow": 16,
    "timeMetric": "ms"
  }
}

Example flow with invalid ( password not passed ) input data and throw as error unchecked

    tags:
      - general
    steps:
      - stepType: request-validation
        config:
          throwAsError: false
          defaultSchema: loginRequestSchema
          targetPath: validations
        name: Request Validation
        description: ""
        condition: ""
      - stepType: jsonata
        config:
          maps:
            - mergeArrayItems: {}
              jsonata: "['data']"
              targetPath: result
        name: JSONATA Map
        description: ""
        condition: ""
    sampleInputSchema: loginRequestSchema
    sampleData:
      username: testUser

Flow result

{
  "doc": {
    "username": "testUser",
    "validations": [
      {
        "keyword": "required",
        "dataPath": "",
        "schemaPath": "#/required",
        "params": {
          "missingProperty": "password"
        },
        "message": "should have required property 'password'"
      }
    ],
    "result": ["data"]
  },
  "errors": [],
  "performance": {
    "steps": [
      {
        "step": "request-validation",
        "executionTime": 12
      },
      {
        "step": "jsonata",
        "executionTime": 0
      }
    ],
    "executionTimeOfFlow": 16,
    "timeMetric": "ms"
  }
}

Testing with API

Example with GET api

The data passed in query params, headers and path params are also considered in request data and used for validation by this step. Below is an example API.

Since Request body schema is not available on the GET apis the step configuration must have default schema selected in the flow. The default schema can be specified as an empty schema (e.g. { "type": "object", "properties": {} }). The query and path parameters will be validated against their definition in the API.

In this api username is passed in header and the password is passed in query param. Below is an example response:

Example with POST api

The data passed in request body is used for validation by this step. Apart from data in body the data in query params, headers and path params are also considered for POST.

We have defined the schema on the api under Request body schema this overrides the default schema defined in the step configuration of flow.

This is applicable to other methods as well like PUT, PATCH etc.

Below is an example API

In this api username and the password is passed in request body. Below is an example response: