Event Ingestion API

The Event Ingestion API provides endpoints for submitting events to Eventara and querying stored events.

Ingest Event

Create a new event for processing.

Endpoint


POST /api/v1/events

Request Body


{
  "eventType": "string (required)",
  "source": "string (required)",
  "timestamp": "string (ISO 8601, optional)",
  "userId": "string (optional)",
  "sessionId": "string (optional)",
  "severity": "string (optional, enum: INFO|WARNING|ERROR|CRITICAL)",
  "tags": {
    "key": "value"
  },
  "metadata": {
    "key": "value"
  }
}

Field Descriptions

Field	Type	Required	Description
eventType	string	Yes	Type of event (e.g., `user.login`, `payment.failed`)
source	string	Yes	Source service or application (e.g., `auth-service`)
timestamp	string	No	Event timestamp in ISO 8601 format. Auto-generated if not provided
userId	string	No	User identifier associated with the event
sessionId	string	No	Session identifier
severity	string	No	Event severity level. Defaults to `INFO`
tags	object	No	Key-value pairs for categorization (string values only)
metadata	object	No	Additional event data (any JSON-serializable values)

Example Request


curl -X POST http://localhost:8080/api/v1/events \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "payment.failed",
    "source": "payment-service",
    "userId": "user_12345",
    "severity": "ERROR",
    "tags": {
      "region": "us-east-1",
      "environment": "production"
    },
    "metadata": {
      "amount": 99.99,
      "currency": "USD",
      "errorCode": "INSUFFICIENT_FUNDS"
    }
  }'

Success Response

Status Code: 202 Accepted


{
  "status": "accepted",
  "eventId": "evt_a1b2c3d4",
  "eventType": "payment.failed",
  "timestamp": "2026-01-12T10:30:45.123Z",
  "message": "Event accepted for processing"
}

Error Responses

Status Code: 400 Bad Request (Validation Failed)


{
  "status": "error",
  "message": "Validation failed",
  "errors": {
    "eventType": "eventType is required (e.g., 'payment.failed')",
    "source": "source is required (e.g:, 'payment-service')"
  }
}

Status Code: 500 Internal Server Error


{
  "status": "error",
  "message": "Failed to process event: <error details>"
}

Batch Ingest Events

Submit multiple events in a single request.

Endpoint


POST /api/v1/events/batch

Current Status

Not Implemented - Returns 501 Not Implemented


{
  "message": "Batch ingestion coming in Module 2!"
}

Get Events

Retrieve events with pagination.

Endpoint


GET /api/v1/events?page={page}&size={size}

Query Parameters

Parameter	Type	Required	Description
page	integer	Yes	Page number (0-based)
size	integer	Yes	Number of events per page (max: 100)

Example Request


curl "http://localhost:8080/api/v1/events?page=0&size=20"

Success Response

Status Code: 200 OK


{
  "content": [
    {
      "id": 1,
      "eventId": "evt_a1b2c3d4",
      "eventType": "user.login",
      "timestamp": "2026-01-12T10:30:45.123Z",
      "source": "auth-service",
      "userId": "user_123",
      "sessionId": null,
      "severity": "INFO",
      "tags": {
        "region": "us-east-1"
      },
      "metadata": {
        "ipAddress": "192.168.1.1"
      },
      "receivedAt": "2026-01-12T10:30:45.456Z",
      "processingLatencyMs": 5,
      "error": false
    }
  ],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 20,
    "sort": {
      "sorted": true,
      "unsorted": false,
      "empty": false
    },
    "offset": 0,
    "paged": true,
    "unpaged": false
  },
  "totalElements": 150,
  "totalPages": 8,
  "last": false,
  "size": 20,
  "number": 0,
  "sort": {
    "sorted": true,
    "unsorted": false,
    "empty": false
  },
  "first": true,
  "numberOfElements": 20,
  "empty": false
}

Notes:

Results are sorted by timestamp in descending order (newest first)
Maximum page size is 100 (automatically limited if exceeded)

Get Events by Type

Retrieve events filtered by event type.

Endpoint


GET /api/v1/events/type/{eventType}?page={page}&size={size}

Path Parameters

Parameter	Type	Required	Description
eventType	string	Yes	Filter by event type

Query Parameters

Same as “Get Events” endpoint.

Example Request


curl "http://localhost:8080/api/v1/events/type/payment.failed?page=0&size=10"

Success Response

Same structure as “Get Events” endpoint, filtered by the specified event type.

Get Event by ID

Retrieve a single event by its unique identifier.

Endpoint


GET /api/v1/events/{eventId}

Path Parameters

Parameter	Type	Required	Description
eventId	string	Yes	Unique event identifier (e.g., `evt_a1b2c3d4`)

Example Request


curl "http://localhost:8080/api/v1/events/evt_a1b2c3d4"

Success Response

Status Code: 200 OK


{
  "id": 1,
  "eventId": "evt_a1b2c3d4",
  "eventType": "payment.failed",
  "timestamp": "2026-01-12T10:30:45.123Z",
  "source": "payment-service",
  "userId": "user_12345",
  "sessionId": null,
  "severity": "ERROR",
  "tags": {
    "region": "us-east-1",
    "environment": "production"
  },
  "metadata": {
    "amount": 99.99,
    "currency": "USD",
    "errorCode": "INSUFFICIENT_FUNDS"
  },
  "receivedAt": "2026-01-12T10:30:45.456Z",
  "processingLatencyMs": 8,
  "error": true
}

Error Response

Status Code: 404 Not Found

Event not found in the system.

Health Check

Check if the service is running.

Endpoint


GET /api/v1/events/health

Example Request


curl "http://localhost:8080/api/v1/events/health"

Success Response

Status Code: 200 OK


{
  "status": "UP",
  "timestamp": "1736679045123"
}

Service Status

Get service information and version.

Endpoint


GET /api/v1/events/test

Example Request


curl "http://localhost:8080/api/v1/events/test"

Success Response

Status Code: 200 OK


{
  "status": "running",
  "service": "Eventara Ingestion Service",
  "version": "0.1.0-SNAPSHOT"
}

Event DTO Structure

Understanding the event data structure:


{
  id: number;                      // Database primary key
  eventId: string;                  // Unique identifier (evt_xxxxx)
  eventType: string;                // Event classification
  timestamp: string;                // ISO 8601 timestamp
  source: string;                   // Source service/application
  userId?: string;                  // Optional user identifier
  sessionId?: string;               // Optional session identifier
  severity: "INFO" | "WARNING" | "ERROR" | "CRITICAL";
  tags: Record<string, string>;    // String key-value pairs
  metadata: Record<string, any>;   // Flexible metadata
  receivedAt: string;              // System receipt timestamp
  processingLatencyMs: number;     // Processing time in milliseconds
  error: boolean;                  // True if severity is ERROR or CRITICAL
}

Best Practices

Event Type Naming: Use namespaced names (e.g., payment.failed, user.signup)
Source Naming: Use consistent service identifiers (e.g., auth-service, payment-service)
Severity Levels:
- INFO: Normal operations
- WARNING: Potential issues
- ERROR: Errors requiring attention
- CRITICAL: Critical failures requiring immediate action
Tags vs Metadata:
- Tags: Use for filtering and categorization (string values)
- Metadata: Use for additional context (any type)
Timestamps: Let the server generate timestamps unless you need precise timing