ai-voicebot/docs/API_EVOLUTION.md

API Evolution Detection System

This system automatically detects when your OpenAPI schema has new endpoints or changed parameters that need to be implemented in the ApiClient class.

How It Works

Automatic Detection

• Development Mode: Automatically runs when api-client.ts is imported during development
• Runtime Checking: Compares available endpoints in the OpenAPI schema with implemented methods
• Console Warnings: Displays detailed warnings about unimplemented endpoints

Schema Comparison

• Hash-based Detection: Detects when the OpenAPI schema file changes
• Endpoint Analysis: Identifies new, changed, or unimplemented endpoints
• Parameter Validation: Suggests checking for parameter changes

Usage

Automatic Checking

The system runs automatically in development mode when you import from api-client.ts:

import { apiClient } from './api-client';
// Check runs automatically after 1 second delay

Command Line Checking

You can run API evolution checks from the command line:

# Full type generation with evolution check
./generate-ts-types.sh

# Quick evolution check only (without regenerating types)
./check-api-evolution.sh

# Or from within the client container
npm run check-api-evolution

Manual Checking

You can manually trigger checks during development:

import { devUtils } from './api-client';

// Check for API evolution
const evolution = await devUtils.checkApiEvolution();

// Force recheck (bypasses once-per-session limit)
devUtils.recheckEndpoints();

Console Output

When unimplemented endpoints are found, you'll see:

Browser Console (development mode):

🚨 API Evolution Detection
🆕 New API endpoints detected:
  • GET /ai-voicebot/api/new-feature (get_new_feature_endpoint)
⚠️  Unimplemented API endpoints:
  • POST /ai-voicebot/api/admin/bulk-action
💡 Implementation suggestions:
Add these methods to ApiClient:
  async adminBulkAction(): Promise<any> {
    return this.request<any>('/ai-voicebot/api/admin/bulk-action', { method: 'POST' });
  }

Command Line:

🔍 API Evolution Check
==================================================
📊 Summary:
   Total endpoints: 8
   Implemented: 7
   Unimplemented: 1

⚠️  Unimplemented API endpoints:
   • POST /ai-voicebot/api/admin/bulk-action
     Admin bulk action endpoint

💡 Implementation suggestions:
Add these methods to the ApiClient class:

  async adminBulkAction(data?: any): Promise<any> {
    return this.request<any>('/ai-voicebot/api/admin/bulk-action', { method: 'POST', body: data });
  }

Configuration

Implemented Endpoints Registry

The system maintains a registry of implemented endpoints in ApiClient. When you add new methods, update the registry:

// In api-evolution-checker.ts
private getImplementedEndpoints(): Set<string> {
  return new Set([
    'GET:/ai-voicebot/api/admin/names',
    'POST:/ai-voicebot/api/admin/set_password',
    // Add new endpoints here:
    'POST:/ai-voicebot/api/admin/bulk-action',
  ]);
}

Schema Location

The system attempts to load the OpenAPI schema from:

• /openapi-schema.json (served by your development server)
• Falls back to hardcoded endpoint list if schema file is unavailable

Development Workflow

When Adding New API Endpoints

1. Add endpoint to FastAPI server (server/main.py)
2. Regenerate types: Run ./generate-ts-types.sh
3. Check console for warnings about unimplemented endpoints
4. Implement methods in ApiClient class
5. Update endpoint registry in the evolution checker
6. Add convenience methods to API namespaces if needed

Example Implementation

When you see a warning like:

⚠️  Unimplemented: POST /ai-voicebot/api/admin/bulk-action

1. Add the method to ApiClient:

async adminBulkAction(data: BulkActionRequest): Promise<BulkActionResponse> {
  return this.request<BulkActionResponse>('/ai-voicebot/api/admin/bulk-action', { 
    method: 'POST', 
    body: data 
  });
}

2. Add to convenience API:

export const adminApi = {
  listNames: () => apiClient.adminListNames(),
  setPassword: (data: AdminSetPassword) => apiClient.adminSetPassword(data),
  clearPassword: (data: AdminClearPassword) => apiClient.adminClearPassword(data),
  bulkAction: (data: BulkActionRequest) => apiClient.adminBulkAction(data), // New
};

3. Update the registry:

private getImplementedEndpoints(): Set<string> {
  return new Set([
    // ... existing endpoints ...
    'POST:/ai-voicebot/api/admin/bulk-action', // Add this
  ]);
}

Benefits

• Prevents Missing Implementations: Never forget to implement new API endpoints
• Development Efficiency: Automatic detection saves time during API evolution
• Type Safety: Works with generated TypeScript types for full type safety
• Code Generation: Provides implementation stubs to get started quickly
• Schema Validation: Detects when OpenAPI schema changes

Production Considerations

• Development Only: Evolution checking only runs in development mode
• Performance: Minimal runtime overhead (single check per session)
• Error Handling: Gracefully falls back if schema loading fails
• Console Logging: All output goes to console.warn/info for easy filtering