Contract Batch

Overview

Helix Spring Boot webservice that shows how to use the Helix batch contracts for mixed-result processing.

Run this example from the shared examples build:

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

What It Shows

• the Helix API starter baseline
• returning BatchResponse from a REST endpoint
• using BatchFailure entries for item-level business failures
• how BatchResponse.status moves between SUCCESS, PARTIAL_SUCCESS, and FAILURE
• how batch contract failures stay inside the batch contract instead of becoming top-level API exceptions

Endpoints

• GET /v1/contract-batch
• POST /v1/contract-batch/orders/process
• GET /liveness
• GET /health

Example success response

{
  "status": "PARTIAL_SUCCESS",
  "items": {
    "success": [
      {
        "orderId": "ORD-100",
        "customerId": "CUST-1",
        "quantity": 3,
        "processingLane": "EXPRESS",
        "result": "PROCESSED"
      }
    ],
    "failed": [
      {
        "id": "ORD-200",
        "code": "CONTRACT-BATCH-409",
        "status": "409",
        "message": "Order cannot be processed while priority is BLOCKED."
      }
    ]
  },
  "summary": {
    "total": 2,
    "success": 1,
    "failed": 1
  }
}

Example validation error response

{
  "request_id": "generated-by-helix",
  "status": "FAILED",
  "timestamp": "2026-03-15T12:34:56+0000",
  "data": {
    "status": 400,
    "message": "Validation Failed"
  }
}

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 batch endpoint returns the Helix BatchResponse contract directly. That means a mixed batch returns status = PARTIAL_SUCCESS, while a fully rejected batch returns status = FAILURE with item-level failures captured under items.failed instead of turning the whole request into a top-level business exception.

./gradlew bootRun

curl http://localhost:8080/v1/contract-batch

curl -X POST http://localhost:8080/v1/contract-batch/orders/process \
  -H 'Content-Type: application/json' \
  -d '{
    "orders": [
      {
        "orderId": "ORD-100",
        "customerId": "CUST-1",
        "quantity": 3,
        "priority": "EXPRESS"
      },
      {
        "orderId": "ORD-200",
        "customerId": "CUST-2",
        "quantity": 1,
        "priority": "BLOCKED"
      },
      {
        "orderId": "ORD-300",
        "customerId": "CUST-3",
        "quantity": 0,
        "priority": "STANDARD"
      }
    ]
  }'