Validation

You can validate requests at the gateway to ensure they are in the correct form before sending them to the respective service.

For some more general information about when to validate requests, see Supporting validation. You can also consult the troubleshooting guide if needed during this task.

Client-side validation

Validation can be performed on the client for simple input checks before sending a request to the gateway, such as ensuring the presence of values for mandatory fields, or verifying that input values are in the correct format.

Client-side validation is configured via the connector's configuration in the same way as parameterized searches. Below is an example configuration for validating that input values for the 'Offence' field start with two letters and two numbers:

{
  "conditions": [
    {
      "id": "searchTerm",
      "label": "Offence",
      "logicalType": "SINGLE_LINE_STRING",
      "mandatory": false,
      "extraStringValidation": {
        "regex": "[A-Za-z]{2}\\d{2}",
        "message": "Case number must start with 2 letters then 2 numbers"
      }
    }
  ]
}

The mandatory property in the config.json file specifies whether a field is required or not.

The extraStringValidation property property allows regex validation be performed with custom error messages to be sent back to the client when a value does not comply with the rule.

You can find out more on accepted condition properties by looking at the /CONFIGURATION_URL endpoint definition in the i2 Connect gateway REST SPI.

Server-side validation

Validation can be performed on the server for more complex inputs.

For example, if there are 3 input fields and you require at least one to be set but they are otherwise optional. In your connector, you can check that the user has defined at least one condition in the request.

In another case, if you have two date fields and want to support searching a range of dates, you can validate that the start date is before the end date.

1. Add the validation endpoint to the connector configuration

In your connector configuration, add the validateUrl property after the existing acquireUrl property as shown in the snippet below. Set the value to the endpoint where you will implement your server-side validation logic.

{
  "id": "nypd-search-service",
  "name": "NYPD Connector: Search",
  "description": "A service for conditional searches.",
  "clientConfigId": "searchForm",
  "acquireUrl": "/search",
  "validateUrl": "/search/validate"
}

2. Implement the validation endpoint

In your code, implement the server-side logic for the validate endpoint using the conditions in the request. The payload that the endpoint receives in the request contains all the same condition and seed information that the acquire endpoint receives.

If validation succeeds according to your logic, return a 200 response code. The body of the response must either be an empty object or an object containing an errorMessage with a null value. For example:

{
  "errorMessage": null
}

If it fails, return an object containing an errorMessage with your error message:

{
  "errorMessage": "This is the error message displayed."
}

When the i2 Connect gateway receives a non-null errorMessage, it does not subsequently send a request to the acquire endpoint.

The following example code provides sample implementations of a validation endpoint in Java and Python.

Java

In the ConnectorController.java file, add the following method:

@RequestMapping(method = RequestMethod.POST, value = "/search/validate",
    consumes = APPLICATION_JSON_VALUE, produces = APPLICATION_JSON_VALUE)
public PayloadValidationResponse searchValidate(@Valid @RequestBody DaodRequest request) {
  final PayloadValidationResponse validationResponse = new PayloadValidationResponse();
  final List<DaodRequestCondition> conditions = request.payload.conditions;
  final boolean conditionPresent = conditions.stream()
      .anyMatch(condition -> condition.value != null);

  if (!conditionPresent) {
    validationResponse.errorMessage = "At least one search field should have a specified value.";
  }
  return validationResponse;
}

Python

In the controller.py class, add the following function and import:

from spi.models.i2_connect_data import I2ConnectData

@controller.route('/search/validate', methods=['POST'])
def search_validate():
    conditions = request.json['payload']['conditions']
    response = I2ConnectData()
    condition_present = False

    for condition in conditions:
        if condition.get('value') is not None:
            condition_present = True

    if not condition_present:
        response.error_message = "At least one search field should have a specified value."

    return response.to_dict()

For more information, see the /VALIDATE_URL endpoint definition in the i2 Connect gateway REST SPI.

3. Reload the i2 Connect gateway

Instruct the i2 Connect gateway to reload the configuration. Test that your new validation has the correct behavior.