Helix Framework Documentation

Example

Custom Requestid

Demonstrates how to replace the default Helix request ID filter with a custom correlation ID strategy. Shows custom request ID generation, propagation through headers and the Helix envelope, global exception handling, and API mapping with helix-mapper.
Group
REST API
Path
examples/rest-api/custom-requestid
Source README

Overview

Helix Spring Boot webservice with a custom request identifier filter.

Run this example from the shared examples build:

Run

Run this example from the shared examples build


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

What It Shows

  • the Helix API starter baseline
  • a custom request-id filter bean on the classpath
  • use of X-Correlation-ID as the public header name
  • pass-through of an incoming correlation ID when present
  • generation of a custom Helix-style ID when the header is absent
  • propagation of that ID into both the Helix response envelope and the response header
  • API-to-service transport mapping implemented with helix-mapper
  • Helix global exception handling for a custom @HelixException
  • preservation of the generated request ID even on structured error responses

Endpoints

  • GET /v1/request-id
  • GET /v1/request-id/required
  • GET /liveness
  • GET /health

Example success response

{
  "request_id": "demo-correlation-id",
  "status": "SUCCESS",
  "timestamp": "2026-03-15T12:34:56+0000",
  "data": {
    "requestId": "demo-correlation-id",
    "headerName": "X-Correlation-ID",
    "generated": false
  }
}

Example error response

{
  "request_id": "custom-request-12345",
  "status": "FAILED",
  "timestamp": "2026-03-15T12:34:56+0000",
  "data": {
    "code": "CUSTOM-REQUESTID-400",
    "status": 400,
    "message": "An incoming correlation ID is required.",
    "attributes": {
      "headerName": "X-Correlation-ID",
      "generatedRequestId": "custom-request-12345"
    }
  }
}

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:

Command

Trying the API


./gradlew bootRun

Command

Trying the API


curl http://localhost:8080/v1/request-id

curl -H 'X-Correlation-ID: demo-correlation-id' http://localhost:8080/v1/request-id

curl http://localhost:8080/v1/request-id/required

curl -H 'X-Correlation-ID: demo-correlation-id' http://localhost:8080/v1/request-id/required