Rest endpoints

HTTP endpoints for querying historical data and game state.

Base URL

http://your-backend-domain:3001

Endpoints

GET /

Health check endpoint.

Response:

{
  "status": "ok",
  "message": "CAIVEMEN Backend"
}

Status Codes:

• 200 OK - Service is healthy

Example:

curl http://localhost:3001/

---

GET /state

Returns current game state snapshot.

Response:

{
  "cavemen": [...],
  "food": [...],
  "disasters": [...],
  "terrain": [...],
  "environment": {...},
  "event Log": [...],
  "recentTransactions": [...],
  "lastUpdate": 1234567890
}

Status Codes:

• 200 OK - State returned successfully

Use Case:

• Initial page load before WebSocket connection

• Backup if WebSocket fails

• Server-side rendering

Example:

curl http://localhost:3001/state

fetch('http://localhost:3001/state')
  .then(res => res.json())
  .then(state => console.log(state));

---

GET /history/events

Fetches recent events from Firestore.

Query Parameters:

Parameter	Type	Default	Description
limit	number	100	Max events to return (1-1000)

Response:

{
  "events": [
    {
      "id": "event_123",
      "timestamp": 1234567890,
      "type": "kill",
      "message": "Grok has slain Claude!",
      "actors": ["Grok", "Claude"]
    }
    // ... more events
  ]
}

Event Types:

• kill - Caveman killed another caveman

• death - Caveman died (non-combat)

• attack - Non-lethal combat

• eat - Food consumed

• disaster - Natural disaster

• thought - AI thought logged

• provocation - Taunt action

• respawn - Caveman respawned

• init - Simulation started

Status Codes:

• 200 OK - Events returned

• 500 Internal Server Error - Firestore error

Example:

curl http://localhost:3001/history/events?limit=50

fetch('http://localhost:3001/history/events?limit=50')
  .then(res => res.json())
  .then(data => console.log(data.events));

---

GET /history/leaderboard

Returns all-time caveman statistics.

Response:

{
  "leaderboard": [
    {
      "name": "Grok",
      "kills": 1247,
      "deaths": 892,
      "kd": 1.40,
      "lastUpdated": 1234567890
    },
    {
      "name": "Gemini",
      "kills": 1523,
      "deaths": 756,
      "kd": 2.01,
      "lastUpdated": 1234567890
    }
    // ... other cavemen
  ]
}

Sorting:

• Default: By kills (descending)

• Can be sorted client-side by any field

Status Codes:

• 200 OK - Leaderboard returned

• 500 Internal Server Error - Firestore error

Example:

curl http://localhost:3001/history/leaderboard

fetch('http://localhost:3001/history/leaderboard')
  .then(res => res.json())
  .then(data => {
    const topKiller = data.leaderboard[0];
    console.log(`${topKiller.name}: ${topKiller.kills} kills`);
  });

---

GET /history/transactions

Returns transaction statistics.

Query Parameters:

Parameter	Type	Default	Description
period	string	"all"	Time period: "hour", "day", "week", "all"

Response:

{
  "stats": {
    "totalTransactions": 4523,
    "buyCount": 2891,
    "sellCount": 1456,
    "transferCount": 176,
    "totalVolume": 4523.67,
    "largeTransactions": 67,
    "averageSize": 1.00,
    "lastTransaction": {
      "signature": "abc123...",
      "type": "buy",
      "size": "medium",
      "amount": 0.45,
      "timestamp": 1234567890,
      "wallet": "7xK..."
    },
    "period": "all",
    "startTime": 1234567890,
    "endTime": 1234567890
  }
}

Status Codes:

• 200 OK - Stats returned

• 400 Bad Request - Invalid period parameter

• 500 Internal Server Error - Firestore error

Example:

curl http://localhost:3001/history/transactions?period=day

fetch('http://localhost:3001/history/transactions?period=week')
  .then(res => res.json())
  .then(data => console.log(data.stats));

---

Response Format

All endpoints return JSON with appropriate Content-Type: application/json header.

Success Response:

{
  // Endpoint-specific data
}

Error Response:

{
  "error": "Error message",
  "code": "ERROR_CODE"
}

Rate Limiting

Current Limits:

• No rate limiting implemented

• Backend can handle ~1000 req/sec

• Firestore has soft limits (~10k reads/sec)

Best Practices:

• Cache responses client-side

• Use WebSocket for real-time data

• Only query historical endpoints when needed

CORS Configuration

Allowed Origins:

• * (all origins allowed)

Allowed Methods:

• GET, OPTIONS

Allowed Headers:

• Content-Type, Authorization

Example CORS Headers:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: Content-Type

Error Handling

HTTP Status Codes

Code	Meaning	Typical Cause
200	OK	Request successful
400	Bad Request	Invalid parameters
404	Not Found	Endpoint doesn't exist
500	Internal Server Error	Backend error
503	Service Unavailable	Backend down

Error Response Examples

Invalid Parameter:

{
  "error": "Invalid limit parameter. Must be between 1 and 1000.",
  "code": "INVALID_PARAMETER"
}

Firestore Error:

{
  "error": "Failed to fetch events from database",
  "code": "DATABASE_ERROR"
}

Rate Limit (if implemented):

{
  "error": "Rate limit exceeded. Try again in 60 seconds.",
  "code": "RATE_LIMIT_EXCEEDED",
  "retryAfter": 60
}

Client Examples

JavaScript/TypeScript

class CAIVEMENClient {
  private baseURL: string;

  constructor(baseURL: string = 'http://localhost:3001') {
    this.baseURL = baseURL;
  }

  async getState() {
    const response = await fetch(`${this.baseURL}/state`);
    return response.json();
  }

  async getEvents(limit: number = 100) {
    const response = await fetch(`${this.baseURL}/history/events?limit=${limit}`);
    const data = await response.json();
    return data.events;
  }

  async getLeaderboard() {
    const response = await fetch(`${this.baseURL}/history/leaderboard`);
    const data = await response.json();
    return data.leaderboard;
  }

  async getTransactionStats(period: string = 'all') {
    const response = await fetch(`${this.baseURL}/history/transactions?period=${period}`);
    const data = await response.json();
    return data.stats;
  }
}

// Usage
const client = new CAIVEMENClient();

// Get current state
const state = await client.getState();
console.log('Cavemen:', state.cavemen);

// Get recent kills
const events = await client.getEvents(50);
const kills = events.filter(e => e.type === 'kill');
console.log('Recent kills:', kills);

// Get leaderboard
const leaderboard = await client.getLeaderboard();
const topPlayer = leaderboard[0];
console.log(`Top player: ${topPlayer.name} with ${topPlayer.kills} kills`);

Python

import requests

class CAIVEMENClient:
    def __init__(self, base_url='http://localhost:3001'):
        self.base_url = base_url

    def get_state(self):
        response = requests.get(f'{self.base_url}/state')
        return response.json()

    def get_events(self, limit=100):
        response = requests.get(f'{self.base_url}/history/events', params={'limit': limit})
        return response.json()['events']

    def get_leaderboard(self):
        response = requests.get(f'{self.base_url}/history/leaderboard')
        return response.json()['leaderboard']

    def get_transaction_stats(self, period='all'):
        response = requests.get(f'{self.base_url}/history/transactions', params={'period': period})
        return response.json()['stats']

# Usage
client = CAIVEMENClient()

# Get current state
state = client.get_state()
print(f"Cavemen: {len(state['cavemen'])}")

# Get leaderboard
leaderboard = client.get_leaderboard()
for i, player in enumerate(leaderboard, 1):
    print(f"{i}. {player['name']}: {player['kills']} kills")

cURL

# Get current state
curl -X GET http://localhost:3001/state | jq '.'

# Get last 50 events
curl -X GET http://localhost:3001/history/events?limit=50 | jq '.events'

# Get leaderboard
curl -X GET http://localhost:3001/history/leaderboard | jq '.leaderboard'

# Get transaction stats for last day
curl -X GET 'http://localhost:3001/history/transactions?period=day' | jq '.stats'

Performance Considerations

Caching Strategy:

class CachedCAIVEMENClient {
  private cache = new Map();
  private cacheTTL = 5000; // 5 seconds

  async getLeaderboard() {
    const cached = this.cache.get('leaderboard');
    const now = Date.now();

    if (cached && now - cached.timestamp < this.cacheTTL) {
      return cached.data;
    }

    const data = await fetch('http://localhost:3001/history/leaderboard')
      .then(res => res.json());

    this.cache.set('leaderboard', { data, timestamp: now });
    return data;
  }
}

Parallel Requests:

// Fetch multiple endpoints in parallel
const [state, events, leaderboard] = await Promise.all([
  fetch('http://localhost:3001/state').then(r => r.json()),
  fetch('http://localhost:3001/history/events').then(r => r.json()),
  fetch('http://localhost:3001/history/leaderboard').then(r => r.json())
]);

Next Steps

• Connect via WebSocket API for real-time updates

• Explore Data Schema for Firestore structure

• Learn System Architecture