Example

Validation

Small Helix REST API example that shows how to use the validators provided by helix-validation.

Group: REST API
Path: examples/rest-api/validation

Overview

Small Helix REST API example that shows how to use the validators provided by helix-validation.

Run this example from the shared examples build:


./gradlew -p examples runExample -Pexample=rest-api/validation --init-script "$(pwd)/helix.init.gradle"

What It Shows

built-in helix-validation annotations on a request body
@PhoneNumber, @ULID, @AddressState, @ZipCode, @AssertIn, and @StrongPassword
a custom cross-field rule using @HelixValidator and a Spring Validator
the standard Helix validation error envelope for invalid requests

Endpoints

POST /v1/validation/enrollments
GET /v1/validation/contacts/lookup?phoneNumber=...
GET /liveness
GET /health
GET /swagger-ui/index.html

Example success response

{
  "request_id": "generated-by-helix",
  "status": "SUCCESS",
  "timestamp": "2026-03-16T12:34:56+0000",
  "data": {
    "customerId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "contactPreference": "SMS",
    "validatorsUsed": [
      "ULID",
      "PhoneNumber",
      "AddressState",
      "ZipCode",
      "AssertIn",
      "StrongPassword",
      "HelixValidator"
    ],
    "message": "Enrollment request accepted after helix-validation checks passed."
  }
}

Example error response

{
  "request_id": "generated-by-helix",
  "status": "FAILED",
  "timestamp": "2026-03-16T12:34:56+0000",
  "data": {
    "status": 400,
    "message": "Validation error.",
    "sub_errors": [
      {
        "name": "customerId",
        "message": "Invalid ULID."
      },
      {
        "name": "enrollmentRequest",
        "message": "enrollmentRequest : smsOptInCode is required when contactPreference is SMS"
      }
    ]
  }
}

Development

Building the Application


./gradlew -p examples/rest-api/validation build --init-script "$(pwd)/helix.init.gradle"

Testing the Application


./gradlew -p examples/rest-api/validation test integration --init-script "$(pwd)/helix.init.gradle"

Trying the API

Run the service:

Then try:


./gradlew -p examples/rest-api/validation bootRun --init-script "$(pwd)/helix.init.gradle"


curl -X POST http://localhost:8080/v1/validation/enrollments \
  -H 'Content-Type: application/json' \
  -d '{
    "customerId":"01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "phoneNumber":"+13125551234",
    "state":"IL",
    "zipCode":"60606-1234",
    "contactPreference":"SMS",
    "portalPassword":"S3curePassword!",
    "smsOptInCode":"JOIN2026"
  }'

curl -X POST http://localhost:8080/v1/validation/enrollments \
  -H 'Content-Type: application/json' \
  -d '{
    "customerId":"not-a-ulid",
    "phoneNumber":"555-1212",
    "state":"Illinois",
    "zipCode":"60606/1234",
    "contactPreference":"PAGER",
    "portalPassword":"weak"
  }'

curl "http://localhost:8080/v1/validation/contacts/lookup?phoneNumber=+13125551234"