Example

Cache Control

Demonstrates how Helix adds default cache headers to GET responses. Shows the default Cache-Control: max-age=1 policy, endpoint-level overrides, and that the filter only applies to GET responses.

Group: REST API
Path: examples/rest-api/cache-control

Source README

Overview

Helix Spring Boot webservice that shows how default Cache-Control headers are added to GET responses and how an endpoint can override them.

Run this example from the shared examples build:


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

What It Shows

the Helix API starter baseline
Helix automatically adding Cache-Control: max-age=1 to GET responses that do not set one
overriding the default cache policy for a specific endpoint by setting Cache-Control explicitly
the cache-control filter applying only to GET responses

Endpoints

GET /v1/cache-control/default
GET /v1/cache-control/custom
POST /v1/cache-control/events
GET /liveness
GET /health

Example success response

{
  "request_id": "generated-by-helix",
  "status": "SUCCESS",
  "timestamp": "2026-03-15T12:34:56+0000",
  "data": {
    "name": "default-cache-policy",
    "message": "This GET endpoint relies on Helix to add the default Cache-Control 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:

The first endpoint shows Helix adding Cache-Control: max-age=1 automatically. The second endpoint sets Cache-Control: no-store, so Helix leaves that override in place. The POST endpoint demonstrates that the default cache-control filter only applies to GET responses.


./gradlew bootRun


curl -i http://localhost:8080/v1/cache-control/default

curl -i http://localhost:8080/v1/cache-control/custom

curl -i -X POST http://localhost:8080/v1/cache-control/events