Example

Enforce App ID

Demonstrates how to require callers to send AppId or X-AppId to a Helix service. Shows the built-in Helix AppId interceptor, success handling for both supported headers, and the global error envelope returned when the header is missing.

Group: REST API
Path: examples/rest-api/enforce-appid

Source README

Overview

Helix Spring Boot webservice that requires callers to send a client application identifier header.

Run this example from the shared examples build:


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

What It Shows

the Helix API starter baseline
the standard Helix response envelope
request identifier handling via X-Request-ID
built-in AppId enforcement via helix.interceptor.appid.enabled=true
support for both AppId and X-AppId
Helix global exception handling for the framework-provided missing-AppId error

Endpoints

GET /v1/appid
GET /liveness
GET /health

Example success response

{
  "request_id": "generated-by-helix",
  "status": "SUCCESS",
  "timestamp": "2026-03-15T12:34:56+0000",
  "data": {
    "appId": "consumer-app",
    "headerName": "AppId"
  }
}

Example error response

{
  "request_id": "generated-by-helix",
  "status": "FAILED",
  "timestamp": "2026-03-15T12:34:56+0000",
  "data": {
    "status": 401,
    "message": "An application identifier is required in the 'AppId' or 'X-AppId' header."
  }
}

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:

Then try:


./gradlew bootRun


curl -H 'AppId: consumer-app' http://localhost:8080/v1/appid

curl -H 'X-AppId: legacy-consumer-app' http://localhost:8080/v1/appid

curl http://localhost:8080/v1/appid