Example

Basic

The smallest representative Helix REST service. Demonstrates the standard Helix response envelope, request IDs, service/resource structure, and global exception handling.

Group: REST API
Path: examples/rest-api/basic

Source README

Overview

Basic Helix RESTful webservice example.

Run this example from the shared examples build:


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

What It Shows

a small feature-based Helix REST API
the standard Helix response envelope
request identifier handling via X-Request-ID
Helix validation error responses
a custom @HelixException handled by the global exception handler

Endpoints

GET /v1/greetings/{name}
POST /v1/greetings
GET /liveness
GET /health
GET /swagger-ui/index.html

Example success response

{
  "request_id": "generated-by-helix",
  "status": "SUCCESS",
  "timestamp": "2026-03-15T12:34:56+0000",
  "data": {
    "name": "Ada",
    "message": "Hello, Ada, from Helix"
  }
}

Example error response

{
  "request_id": "generated-by-helix",
  "status": "FAILED",
  "timestamp": "2026-03-15T12:34:56+0000",
  "data": {
    "code": "BASIC-GREETING-404",
    "status": 404,
    "message": "Greeting not found.",
    "attributes": {
      "requestedName": "missing"
    }
  }
}

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 http://localhost:8080/v1/greetings/Ada

curl -X POST http://localhost:8080/v1/greetings \
  -H 'Content-Type: application/json' \
  -d '{"name":"Grace"}'

curl http://localhost:8080/v1/greetings/missing

curl -X POST http://localhost:8080/v1/greetings \
  -H 'Content-Type: application/json' \
  -d '{"name":""}'