Helix Framework Documentation

Example

Actuator Readiness

Demonstrates how Helix readiness is managed through the readiness actuator endpoint. Shows the management-port readiness contract, marking the instance out of service and back in service, and the corresponding readiness view from application code.
Group
REST API
Path
examples/rest-api/actuator-readiness
Source README

Overview

Helix Spring Boot webservice that shows how the readiness actuator can mark a service in or out of service during deployment workflows.

Run this example from the shared examples build:

Run

Run this example from the shared examples build


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

What It Shows

  • the Helix API starter baseline
  • enabling the built-in readiness actuator with management.endpoint.readiness.enabled=true
  • a normal business endpoint while the instance is marked in service
  • checking readiness through the management endpoint on the management port
  • marking the instance out of service and back in service through the readiness actuator

Endpoints

  • GET /v1/actuator-readiness/status
  • GET /readiness
  • POST /readiness
  • DELETE /readiness
  • GET /liveness
  • GET /health

Example success response

{
  "request_id": "generated-by-helix",
  "status": "SUCCESS",
  "timestamp": "2026-03-15T12:34:56+0000",
  "data": {
    "acceptingTraffic": true,
    "message": "Instance is marked in service and ready to receive traffic."
  }
}

Example management response

{
  "request_id": "generated-by-helix",
  "status": "SUCCESS",
  "timestamp": "2026-03-15T12:34:56+0000",
  "data": {
    "ready": true
  }
}

Development

Building the Application

Run the following command to build the service:

Command

Building the Application


./gradlew clean build

Testing the Application

Run the following command to run the service tests:

Command

Testing the Application


./gradlew test
./gradlew integration

Trying the API

Run the service:

Then try:

The application endpoint on port 8080 stays available for demonstration purposes, while the readiness actuator on port 8081 reflects whether the instance should be considered in or out of service by deployment tooling. This is a useful pattern for draining traffic before a rollout step and returning the instance to service when it is ready again.

Command

Trying the API


./gradlew bootRun

Command

Trying the API


curl http://localhost:8080/v1/actuator-readiness/status

curl http://localhost:8081/readiness

curl -X DELETE http://localhost:8081/readiness

curl http://localhost:8081/readiness

curl -X POST http://localhost:8081/readiness

curl http://localhost:8081/readiness