HOW_IT_WORKS.md

API Integration - How It Works

This guide shows how your es6Api has been integrated into Payload CMS with collection-based management.

🏗️ Architecture Overview

Your API is now managed through Payload CMS collections:

┌─────────────────────────────────────────────────────┐
│                  Payload CMS Admin                  │
│  (Manage Routes, Functions, Keys, Users visually)   │
└─────────────────────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────┐
│              Payload Collections                    │
│  • Routes   • Functions  • Endpoints                │
│  • Keys     • Users      • Media                    │
└─────────────────────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────┐
│           API Integration Layer                     │
│  (src/lib/apiIntegration.ts)                       │
│  • Authentication  • Authorization                  │
│  • Dynamic routing • Function execution             │
└─────────────────────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────┐
│         Your es6Api Functions                       │
│  • Knowi   • FileMaker  • GPT                      │
│  • Anthropic  • Ollama                             │
└─────────────────────────────────────────────────────┘

🚀 Getting Started

1. Start Payload CMS

cd /Users/mroberts/Development/dev_JavaScript/personal/cctest/api-command
pnpm dev

This starts Payload on http://localhost:3000

2. Seed Your API Data

Populate the collections with your existing es6Api routes:

pnpm tsx src/scripts/seedApiData.ts

This creates:

• ✅ 2 API keys (Admin, Knowi)
• ✅ 5 Functions (knowi, filemaker, gpt, anthropic, ollama)
• ✅ 1 Endpoint (Development)
• ✅ 5 Routes (GET /api/knowi, POST /api/gptChat, etc.)

3. Access the Admin Panel

Go to http://localhost:3000/admin and you'll see:

📁 Collections
  👥 Users
  🔑 Keys
  🛣️  Routes
  ⚙️  Functions
  🌐 Endpoints
  📸 Media

📋 Collections Explained

1. Keys Collection

Manages API authentication keys with types and permissions.

Example Key:

{
  name: "Admin Key",
  keyValue: "sk_abc123xyz",
  keyType: "admin",
  allowedRoutes: [/* route IDs */],
  rateLimit: { windowMs: 900000, maxRequests: 1000 },
  isActive: true
}

2. Functions Collection

Stores your actual API function handlers from es6Api.

Example Function:

{
  name: "getKnowiRecords",
  service: "knowi",
  functionPath: "services/knowi/knowiDb.js",
  exportName: "getPaginatedKnowiRecords",
  parameters: [
    { paramName: "page", paramType: "number", required: false },
    { paramName: "limit", paramType: "number", required: false }
  ],
  responseType: "json",
  isActive: true
}

3. Routes Collection

Defines API endpoints that map to functions.

Example Route:

{
  name: "Get Knowi Records",
  path: "/api/knowi",
  method: "GET",
  function: "getKnowiRecords", // linked to Functions collection
  requiresAuth: true,
  allowedKeys: ["knowi-key-id"],
  isActive: true
}

4. Endpoints Collection

Manages different API environments.

Example Endpoint:

{
  name: "Development API",
  baseUrl: "http://localhost:3000/api",
  environment: "development",
  version: "v1"
}

5. Users Collection

Extended with API permissions and key relationships.

🔧 How to Use

Making API Calls

Your API now works through Payload's server. All endpoints require authentication via the key parameter:

Example 1: Get Knowi Records

curl "http://localhost:3000/api/knowi?key=knowi-key-here&page=1&limit=10"

Example 2: GPT Chat

curl -X POST http://localhost:3000/api/gptChat \
  -H "Content-Type: application/json" \
  -d '{
    "key": "admin-key-here",
    "message": "Hello, GPT!"
  }'

Example 3: Using Header Authentication

curl http://localhost:3000/api/knowi \
  -H "x-api-key: knowi-key-here"

Managing via Admin UI

1. Go to Admin: http://localhost:3000/admin
2. Navigate to Collections: Click on Routes, Keys, Functions, etc.
3. Create/Edit: Add new routes, update functions, manage keys

Example: Adding a New Route

1. Go to Routes collection
2. Click Create New
3. Fill in:
   • Name: "Delete Record"
   • Path: "/api/deleteRecord"
   • Method: "DELETE"
   • Function: Select from dropdown (links to Functions collection)
   • Allowed Keys: Select which keys can access this route
   • Requires Auth: ✓
4. Save

The route is immediately available at DELETE /api/deleteRecord!

🔐 Authentication Flow

1. Client sends request with API key
   ↓
2. authenticateApiKey() middleware checks Keys collection
   ↓
3. Validates: key exists, is active, not expired
   ↓
4. Updates: lastUsedAt, usageCount
   ↓
5. validateRoutePermissions() checks route access
   ↓
6. Validates: route exists, key has permission
   ↓
7. executeFunctionHandler() runs the function
   ↓
8. Dynamically imports and executes handler
   ↓
9. Returns response to client

📝 Adding Your es6Api Functions

To integrate an existing function from your es6Api:

Step 1: Create Function Entry

In Payload Admin → Functions → Create New:

Name: myCustomFunction
Service: filemaker (or gpt, knowi, etc.)
Function Path: services/filemaker/myFile.js
Export Name: myFunctionName

Step 2: Create Route Entry

In Payload Admin → Routes → Create New:

Name: My Custom Endpoint
Path: /api/custom
Method: POST
Function: Select "myCustomFunction"
Requires Auth: Yes
Allowed Keys: Select your keys

Step 3: Test It

curl -X POST http://localhost:3000/api/custom \
  -H "x-api-key: your-key" \
  -d '{"data": "test"}'

🎯 Key Benefits

Before (es6Api/server.js)

• ❌ Hardcoded routes in server.js
• ❌ Manual key management in code
• ❌ No UI to manage endpoints
• ❌ Changes require code edits + restart

After (Payload Integration)

• ✅ Routes managed via UI
• ✅ Keys managed in database
• ✅ Visual admin panel
• ✅ Add routes without coding
• ✅ Track API usage automatically
• ✅ Built-in user management
• ✅ Role-based access control

🔄 Migration Checklist

From your es6Api to Payload:

• Collections created (Routes, Functions, Keys, etc.)
• Integration layer built (apiIntegration.ts)
• Seed script ready
• Run seed script: pnpm tsx src/scripts/seedApiData.ts
• Copy function files from es6Api/src to api-command/src
• Update function paths in Functions collection
• Test each endpoint
• Update client applications with new URLs
• Set up production environment variables

📚 Example Workflows

Workflow 1: Create a New API Key for a Partner

1. Admin UI → Keys → Create New
2. Name: "Partner XYZ"
3. Key Type: "standard"
4. Allowed Routes: Select specific routes
5. Rate Limit: 100 requests/15min
6. Save → Share key with partner

Workflow 2: Temporarily Disable a Route

1. Admin UI → Routes
2. Find the route
3. Uncheck "Active"
4. Save → Route immediately unavailable

Workflow 3: Monitor API Usage

1. Admin UI → Keys
2. Click on any key
3. View: Last Used At, Usage Count
4. See which user it belongs to

🐛 Troubleshooting

Error: "API key is required"

• Add ?key=your-key to URL or x-api-key header

Error: "Route not found"

• Check Routes collection - is it Active?
• Verify path and method match

Error: "Function not found"

• Check Functions collection - is it Active?
• Verify functionPath exists in your project

Error: "Invalid API key"

• Check Keys collection - is key value correct?
• Check isActive = true
• Check expiresAt hasn't passed

🎓 Next Steps

1. Copy your es6Api functions to this project's src directory
2. Update function paths in the Functions collection
3. Create more routes via the admin UI
4. Set up production with proper environment variables
5. Monitor usage through the Keys collection

---

Your API is now fully integrated with Payload CMS! 🎉

Everything is manageable through the admin UI at http://localhost:3000/admin