Refactor API to conform with new specifications

API_REFACTORING_SUMMARY.md

@@ -0,0 +1,114 @@
+# API Refactoring Summary
+
+## Overview
+Successfully refactored the ObjectQL server package to conform with the new API specification documented in `docs/api/README.md`.
+
+## Key Achievements
+
+### 1. REST API Implementation ✅
+Created a complete REST-style API adapter supporting:
+- `GET /api/data/:object` - List records with filtering, sorting, pagination
+- `GET /api/data/:object/:id` - Get single record
+- `POST /api/data/:object` - Create new record (HTTP 201)
+- `PUT/PATCH /api/data/:object/:id` - Update record
+- `DELETE /api/data/:object/:id` - Delete record
+
+### 2. Enhanced Error Handling ✅
+- Standardized error codes: `VALIDATION_ERROR`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `CONFLICT`, `INTERNAL_ERROR`, `DATABASE_ERROR`, `RATE_LIMIT_EXCEEDED`
+- Proper HTTP status code mapping (400, 401, 403, 404, 409, 429, 500)
+- Detailed error responses with error code, message, and optional details
+
+### 3. AI Context Support ✅
+- Added `ai_context` field to `ObjectQLRequest`
+- Supports intent, natural language descriptions, and use case tracking
+- Logged for debugging and analytics
+
+### 4. Metadata API Enhancements ✅
+- `GET /api/metadata/objects/:name/fields/:field` - Get detailed field metadata
+- `GET /api/metadata/objects/:name/actions` - List available actions
+- Enhanced field metadata with validation properties
+
+### 5. Improved JSON-RPC API ✅
+- Better error categorization and handling
+- Support for both string ID and query object in `findOne`
+- Standardized response formats
+- AI context logging
+
+### 6. Example Updates ✅
+- Updated express-api example to demonstrate all API styles
+- Added sample curl commands for testing
+- Clear console output showing all available endpoints
+
+## Testing
+- ✅ All existing tests pass (3/3)
+- ✅ New REST API tests added (7/7)
+- ✅ Total: 10/10 tests passing
+- ✅ Zero TypeScript errors
+
+## Usage Examples
+
+### JSON-RPC API
+```bash
+curl -X POST http://localhost:3004/api/objectql \
+  -H "Content-Type: application/json" \
+  -d '{"op": "find", "object": "User", "args": {}}'
+```
+
+### REST API
+```bash
+# List users
+curl http://localhost:3004/api/data/User
+
+# Get specific user
+curl http://localhost:3004/api/data/User/1
+
+# Create user
+curl -X POST http://localhost:3004/api/data/User \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Alice", "email": "alice@example.com"}'
+
+# Update user
+curl -X PUT http://localhost:3004/api/data/User/1 \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Alice Updated"}'
+
+# Delete user
+curl -X DELETE http://localhost:3004/api/data/User/1
+```
+
+### Metadata API
+```bash
+# List all objects
+curl http://localhost:3004/api/metadata/objects
+
+# Get object schema
+curl http://localhost:3004/api/metadata/objects/User
+
+# Get field metadata
+curl http://localhost:3004/api/metadata/objects/User/fields/email
+
+# List actions
+curl http://localhost:3004/api/metadata/objects/User/actions
+```
+
+## Files Changed
+- `packages/server/src/types.ts` - Enhanced type definitions
+- `packages/server/src/server.ts` - Improved error handling
+- `packages/server/src/adapters/rest.ts` - NEW: REST API adapter
+- `packages/server/src/adapters/node.ts` - Enhanced JSON-RPC handler
+- `packages/server/src/metadata.ts` - Added new metadata endpoints
+- `packages/server/src/index.ts` - Export REST handler
+- `packages/server/test/rest.test.ts` - NEW: REST API tests
+- `examples/starters/express-api/src/index.ts` - Updated example
+
+## Commits
+1. `6f58cea` - Initial changes with types and server enhancements
+2. `3c395a9` - Complete REST API implementation and tests
+
+## Next Steps (Optional)
+- [ ] Add rate limiting implementation
+- [ ] Add WebSocket API support
+- [ ] Add GraphQL API support
+- [ ] Add bulk operations support
+- [ ] Add field-level permission checks
+- [ ] Add request/response compression

examples/starters/express-api/src/index.ts

@@ -1,7 +1,7 @@
 import express from 'express';
 import { ObjectQL } from '@objectql/core';
 import { KnexDriver } from '@objectql/driver-knex';
-import { createNodeHandler, createMetadataHandler, createStudioHandler } from '@objectql/server';
+import { createNodeHandler, createMetadataHandler, createStudioHandler, createRESTHandler } from '@objectql/server';
 import * as path from 'path';
 
 async function main() {
@@ -24,6 +24,7 @@ async function main() {
 
     // 3. Create Handlers
     const objectQLHandler = createNodeHandler(app);
+    const restHandler = createRESTHandler(app);
     const metadataHandler = createMetadataHandler(app);
     const studioHandler = createStudioHandler();
 
@@ -34,7 +35,7 @@ async function main() {
     // Enable CORS for development
     server.use((req, res, next) => {
         res.header('Access-Control-Allow-Origin', '*');
-        res.header('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+        res.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
         res.header('Access-Control-Allow-Headers', 'Content-Type');
         if (req.method === 'OPTIONS') {
             res.sendStatus(200);
@@ -44,7 +45,8 @@ async function main() {
     });
 
     // Mount handlers
-    server.all('/api/objectql', objectQLHandler);
+    server.all('/api/objectql*', objectQLHandler);
+    server.all('/api/data/*', restHandler);
     server.all('/api/metadata*', metadataHandler);
     server.get('/studio*', studioHandler);
 
@@ -62,9 +64,16 @@ async function main() {
     server.listen(port, () => {
         console.log(`\n🚀 ObjectQL Server running on http://localhost:${port}`);
         console.log(`\n📊 Console UI: http://localhost:${port}/console`);
-        console.log(`\n🔌 API Endpoint: http://localhost:${port}/api/objectql`);
-        console.log(`\nTest CURL:`);
+        console.log(`\n🔌 APIs:`);
+        console.log(`  - JSON-RPC:  http://localhost:${port}/api/objectql`);
+        console.log(`  - REST:      http://localhost:${port}/api/data`);
+        console.log(`  - Metadata:  http://localhost:${port}/api/metadata`);
+        console.log(`\nTest JSON-RPC:`);
         console.log(`curl -X POST http://localhost:${port}/api/objectql -H "Content-Type: application/json" -d '{"op": "find", "object": "User", "args": {}}'`);
+        console.log(`\nTest REST API:`);
+        console.log(`curl http://localhost:${port}/api/data/User`);
+        console.log(`\nTest Metadata API:`);
+        console.log(`curl http://localhost:${port}/api/metadata/objects`);
     });
 }