Event Ledger API

A RESTful API for managing financial transaction events with idempotency and out-of-order event handling.

Tech Stack

• Java 20
• Spring Boot 3.5.14
• Spring Data JPA
• H2 In-Memory Database
• Maven

Prerequisites

• Java 20 or higher
• Git

Setup

Clone the repository:

git clone https://github.com/rushikeshMoreDev/event-ledger-api.git
cd api

How to Start the Application

Mac/Linux:

./mvnw spring-boot:run

Windows:

mvnw.cmd clean spring-boot:run

App runs on http://localhost:8080

How to Run the Tests

Mac/Linux:

./mvnw test

Windows:

mvnw.cmd test

API Endpoints

Method	Endpoint	Description
POST	/api/v1/events	Submit a transaction event
GET	/api/v1/events/{id}	Get event by ID
GET	/api/v1/events?account={accountId}	List events ordered by timestamp
GET	/api/v1/accounts/{accountId}/balance	Get computed balance

Sample Request

POST /api/v1/events
Content-Type: application/json

{
  "eventId": "evt-001",
  "accountId": "acct-123",
  "type": "CREDIT",
  "amount": 150.00,
  "currency": "USD",
  "eventTimestamp": "2026-05-15T14:02:11Z",
  "metadata": {
    "source": "mainframe-batch",
    "batchId": "B-9042"
  }
}

Sample Responses

Submit Event (201 Created)

{
  "id": "uuid-001",
  "eventId": "evt-001",
  "accountId": "acct-123",
  "type": "CREDIT",
  "amount": 150.00,
  "currency": "USD",
  "eventTimestamp": "2026-05-15T14:02:11Z",
  "receivedAt": "2026-05-23T12:00:00Z"
}

Get Balance (200 OK)

{
  "accountId": "acct-123",
  "balance": 150.00,
  "currency": "USD"
}

Validation Error (400 Bad Request)

{
  "status": 400,
  "error": "Validation Failed",
  "messages": ["type: type must be CREDIT or DEBIT"],
  "timestamp": "2026-05-23T12:00:00Z"
}

Key Features

• Idempotency — duplicate eventId returns original event without altering balance
• Out-of-order tolerance — events always returned sorted by eventTimestamp regardless of arrival order
• Balance computation — net balance = sum(CREDIT) - sum(DEBIT)
• Validation — rejects missing fields, invalid types, zero/negative amounts

H2 Console (Development)

Access the database at http://localhost:8080/h2-console

• JDBC URL: jdbc:h2:mem:eventledgerdb
• Username: sa
• Password: (leave blank)

Running with Docker (Optional)

docker compose up