Helix Framework Documentation

Example

Killswitch

Demonstrates how to control the Helix kill switch through the actuator management port. Shows the management endpoint contract, Helix-enveloped actuator responses, and the standard 503 business error returned while traffic is blocked.
Group
REST API
Path
examples/rest-api/killswitch
Source README

Overview

Helix Spring Boot webservice that shows how the kill switch actuator can take a service out of traffic.

Run this example from the shared examples build:

Run

Run this example from the shared examples build


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

What It Shows

  • the Helix API starter baseline
  • enabling the built-in kill switch actuator with management.endpoint.killswitch.enabled=true
  • normal business traffic while the kill switch is inactive
  • toggling the kill switch through the management endpoint on the management port
  • Helix returning a standard 503 error envelope when traffic is blocked

Endpoints

  • GET /v1/killswitch/status
  • GET /killswitch
  • POST /killswitch
  • DELETE /killswitch
  • GET /liveness
  • GET /health

Example success response

{
  "request_id": "generated-by-helix",
  "status": "SUCCESS",
  "timestamp": "2026-03-15T12:34:56+0000",
  "data": {
    "serviceAvailable": true,
    "message": "Traffic is flowing normally."
  }
}

Example management response

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

Example error response

{
  "request_id": "generated-by-helix",
  "status": "FAILED",
  "timestamp": "2026-03-15T12:34:56+0000",
  "data": {
    "status": 503,
    "message": "Service Unavailable"
  }
}

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 business endpoint on port 8080 works normally until you activate the kill switch through the management port 8081. The actuator responses are also wrapped in the standard Helix response envelope. Once active, Helix blocks incoming requests and returns the standard 503 error envelope. Deactivating the kill switch lets traffic flow again immediately.

Command

Trying the API


./gradlew bootRun

Command

Trying the API


curl http://localhost:8080/v1/killswitch/status

curl http://localhost:8081/killswitch

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

curl http://localhost:8080/v1/killswitch/status

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

curl http://localhost:8080/v1/killswitch/status