Sanity Check

Overview

Helix Spring Boot webservice that shows how to create a custom Helix sanity check and have it fail application startup

before the service begins accepting requests.

Run this example from the shared examples build:

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

What It Shows

• the Helix API starter baseline
• creating a custom HelixSanityCheck bean
• validating application-specific startup requirements in custom code
• failing startup with HelixSanityCheckException when a required property is missing or invalid
• exposing the configured requirement through a normal business endpoint once the sanity check passes

Endpoints

• GET /v1/sanity-check/requirements
• GET /liveness
• GET /health

Example success response

{
  "request_id": "generated-by-helix",
  "status": "SUCCESS",
  "timestamp": "2026-03-15T12:34:56+0000",
  "data": {
    "propertyName": "demo.partner.base-url",
    "configuredValue": "https://partner.example.com",
    "rule": "The partner base URL must be configured and must use HTTPS."
  }
}

Example startup failure

com.helixframework.api.sanity.HelixSanityCheckException:
Partner API base URL must be configured with the 'demo.partner.base-url' property.

Development

Building the Application

Run the following command to build the service:

./gradlew clean build

Testing the Application

Run the following command to run the service tests:

./gradlew test
./gradlew integration

Trying the API

Run the service with the required property:

You can also provide the same setting as an environment variable or JVM system property:

Then try:

If you start the service without demo.partner.base-url, or if you set it to a non-HTTPS URL, the custom sanity check will fail startup before the application begins serving traffic.

./gradlew bootRun --args='--demo.partner.base-url=https://partner.example.com'

DEMO_PARTNER_BASE_URL=https://partner.example.com ./gradlew bootRun

./gradlew bootRun --jvm-args='-Ddemo.partner.base-url=https://partner.example.com'

curl http://localhost:8080/v1/sanity-check/requirements