Contract Pagination

Overview

Helix Spring Boot webservice that shows how to use the Helix offset and cursor pagination contracts.

Run this example from the shared examples build:

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

What It Shows

• the Helix API starter baseline
• returning HateoasOffsetPaginatedResponse for page-number style pagination
• returning HateoasCursorPaginatedResponse for cursor-based pagination
• adding pagination navigation links through the _links HAL section
• how the two contracts differ in offset / limit versus cursor

Endpoints

• GET /v1/contract-pagination/offset?offset=0&limit=2
• GET /v1/contract-pagination/cursor?cursor=book-202
• GET /liveness
• GET /health

Example offset response

{
  "count": 2,
  "offset": 0,
  "limit": 2,
  "items": [
    {
      "bookId": "book-101",
      "title": "Domain-Driven Helix",
      "author": "Ada Lovelace"
    },
    {
      "bookId": "book-202",
      "title": "Observability by Default",
      "author": "Grace Hopper"
    }
  ],
  "_links": {
    "self": {
      "href": "/v1/contract-pagination/offset?offset=0&limit=2"
    },
    "next": {
      "href": "/v1/contract-pagination/offset?offset=2&limit=2"
    }
  }
}

Example cursor response

{
  "count": 2,
  "cursor": "book-404",
  "items": [
    {
      "bookId": "book-202",
      "title": "Observability by Default",
      "author": "Grace Hopper"
    },
    {
      "bookId": "book-303",
      "title": "Contracts First APIs",
      "author": "Katherine Johnson"
    }
  ],
  "_links": {
    "self": {
      "href": "/v1/contract-pagination/cursor?cursor=book-202"
    },
    "next": {
      "href": "/v1/contract-pagination/cursor?cursor=book-404"
    }
  }
}

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 offset endpoint demonstrates count plus offset and limit, while the cursor endpoint demonstrates count plus the next cursor token. Both publish _links so clients can discover the next page URI without reconstructing it manually.

./gradlew bootRun

curl "http://localhost:8080/v1/contract-pagination/offset?offset=0&limit=2"

curl "http://localhost:8080/v1/contract-pagination/cursor?cursor=book-202"