Helix Framework Documentation

Example

Deprecation

Demonstrates how to mark an API deprecated with Helix and communicate migration details through response headers. Shows @ApiDeprecated, Deprecation and Sunset headers, and Link headers for deprecation docs and the successor endpoint.
Group
REST API
Path
examples/rest-api/deprecation
Source README

Overview

Helix Spring Boot webservice that shows how to mark APIs deprecated and communicate the migration path to clients.

Run this example from the shared examples build:

Run

Run this example from the shared examples build


./gradlew -p examples runExample -Pexample=rest-api/deprecation --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 deprecation headers via @ApiDeprecated
  • client-facing Deprecation, Sunset, and Link headers
  • communicating both migration documentation and the successor endpoint to callers

Endpoints

  • GET /v1/announcements/current
  • GET /v2/announcements/current
  • GET /liveness
  • GET /health

Example success response

{
  "request_id": "generated-by-helix",
  "status": "SUCCESS",
  "timestamp": "2026-03-15T12:34:56+0000",
  "data": {
    "version": "v1",
    "message": "Announcements v1 is deprecated. Please migrate to /v2/announcements/current.",
    "replacementVersion": "v2"
  }
}

Example deprecation headers

Deprecation: version=v1, date=Thu, 13 Mar 2025 23:59:59 GMT
Sunset: Wed, 31 Dec 2026 23:59:59 GMT
Link: <https://www.helixframework.com/docs/api/deprecations/announcements-v1>; rel="deprecation"
Link: </v2/announcements/current>; rel="successor-version"

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 v1 response includes Helix deprecation headers that tell clients the API is deprecated, when it sunsets, where to read more, and which endpoint replaces it. The v2 response returns the current payload without any deprecation metadata.

Command

Trying the API


./gradlew bootRun

Command

Trying the API


curl -i http://localhost:8080/v1/announcements/current

curl -i http://localhost:8080/v2/announcements/current