Helix Framework Documentation

Example

Envelope

Demonstrates how response enveloping works in Helix services. Shows automatic enveloping, explicit ResponseEnvelope usage, and disabling automatic enveloping for one endpoint with @DisableResponseEnvelope.
Group
REST API
Path
examples/rest-api/envelope
Source README

Overview

Helix Spring Boot webservice that shows the different response enveloping options available to Helix services.

Run this example from the shared examples build:

Run

Run this example from the shared examples build


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

What It Shows

  • the Helix API starter baseline
  • automatic response enveloping for plain DTO responses
  • explicit response enveloping with ResponseEnvelope
  • disabling automatic enveloping for a specific endpoint with @DisableResponseEnvelope
  • request identifier handling via X-Request-ID

Endpoints

  • GET /v1/envelope/automatic
  • GET /v1/envelope/explicit
  • GET /v1/envelope/raw
  • GET /liveness
  • GET /health

Example success response

{
  "request_id": "generated-by-helix",
  "status": "SUCCESS",
  "timestamp": "2026-03-15T12:34:56+0000",
  "data": {
    "mode": "automatic",
    "message": "Helix wrapped this plain DTO automatically."
  }
}

Example raw response

{
  "mode": "raw",
  "message": "This endpoint disables automatic enveloping with @DisableResponseEnvelope."
}

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 automatic endpoint returns a plain DTO and Helix wraps it for you. The explicit endpoint returns a ResponseEnvelope directly, which Helix leaves alone instead of double-wrapping. The raw endpoint opts out of automatic wrapping for that method only with @DisableResponseEnvelope.

Command

Trying the API


./gradlew bootRun

Command

Trying the API


curl http://localhost:8080/v1/envelope/automatic

curl http://localhost:8080/v1/envelope/explicit

curl http://localhost:8080/v1/envelope/raw