Helix Framework Documentation

Example

ETag

Demonstrates how to enable the built-in Helix shallow ETag filter. Shows the first GET returning an ETag, a follow-up If-None-Match request returning 304 Not Modified, and scoping the filter to selected URL patterns.
Group
REST API
Path
examples/rest-api/etag
Source README

Overview

Helix Spring Boot webservice that demonstrates how to enable and use the built-in Helix ETag 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/etag --init-script "$(pwd)/helix.init.gradle"

What It Shows

  • enabling the built-in Helix shallow ETag filter with helix.filter.etag.enabled=true
  • scoping the filter to selected endpoints with helix.filter.etag.url-patterns
  • disabling response enveloping for the ETag endpoint so the response body stays stable between requests
  • receiving an ETag header on the first GET
  • sending If-None-Match on a subsequent GET
  • getting a 304 Not Modified response when the representation has not changed

Endpoints

  • GET /v1/etag/articles/{slug}
  • GET /liveness
  • GET /health

Example success response

{
  "slug": "getting-started",
  "title": "Getting Started with Helix",
  "body": "Enable the Helix ETag filter to let the framework generate shallow ETags for stable GET responses."
}

Example 304 response

HTTP/1.1 304 Not Modified
ETag: "0a12bc34d56ef789..."

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 -i http://localhost:8080/v1/etag/articles/getting-started

curl -i \
  -H 'If-None-Match: "<etag-from-first-response>"' \
  http://localhost:8080/v1/etag/articles/getting-started