Helix Framework Documentation

Example

Contract Hateoas

Demonstrates how to use the Helix HATEOAS response contracts. Shows HateoasCollectionResponse, a custom resource extending HateoasResponse, and _links with navigation and action metadata.
Group
REST API
Path
examples/rest-api/contract-hateoas
Source README

Overview

Helix Spring Boot webservice that shows how to use the Helix HATEOAS response contracts.

Run this example from the shared examples build:

Run

Run this example from the shared examples build


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

What It Shows

  • the Helix API starter baseline
  • returning a collection with HateoasCollectionResponse
  • returning a single resource that extends HateoasResponse
  • adding _links with self, collection navigation, and action links
  • attaching HTTP method metadata to action links with HalLink

Endpoints

  • GET /v1/contract-hateoas/books
  • GET /v1/contract-hateoas/books/{bookId}
  • GET /liveness
  • GET /health

Example collection response

{
  "count": 2,
  "items": [
    {
      "bookId": "book-101",
      "title": "Domain-Driven Helix",
      "author": "Ada Lovelace",
      "status": "AVAILABLE"
    },
    {
      "bookId": "book-202",
      "title": "Observability by Default",
      "author": "Grace Hopper",
      "status": "CHECKED_OUT"
    }
  ],
  "_links": {
    "self": {
      "href": "/v1/contract-hateoas/books"
    },
    "first": {
      "href": "/v1/contract-hateoas/books/book-101"
    }
  }
}

Example item response

{
  "bookId": "book-101",
  "title": "Domain-Driven Helix",
  "author": "Ada Lovelace",
  "status": "AVAILABLE",
  "summary": "A practical guide to structuring Helix services around feature boundaries.",
  "_links": {
    "self": {
      "href": "/v1/contract-hateoas/books/book-101"
    },
    "collection": {
      "href": "/v1/contract-hateoas/books"
    },
    "reserve": {
      "href": "/v1/contract-hateoas/books/book-101/reservations",
      "meta": {
        "method": "POST"
      }
    }
  }
}

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 collection endpoint demonstrates the Helix collection contract with navigation links, while the item endpoint shows a custom resource extending HateoasResponse and publishing discoverable action links for clients.

Command

Trying the API


./gradlew bootRun

Command

Trying the API


curl http://localhost:8080/v1/contract-hateoas/books

curl http://localhost:8080/v1/contract-hateoas/books/book-101