# UCXI API Standardization - UCXL Response Formats This document describes the standardized API response formats implemented for the UCXI server, addressing Issues 004 and 010. ## Overview The UCXI API now uses standardized UCXL response and error formats that provide: - Consistent response structures across all endpoints - Proper error categorization with machine-readable codes - Request tracing with unique request IDs - Comprehensive status and configuration endpoints ## UCXL Response Format ### Success Responses All successful API responses follow this structure: ```json { "response": { "code": "UCXL-200-SUCCESS", "message": "Request completed successfully", "data": { // Actual response data here }, "details": { // Optional additional details }, "request_id": "20240128-143052-abc12def", "timestamp": "2024-01-28T14:30:52.123Z" } } ``` #### Success Code Examples: - `UCXL-200-SUCCESS` - Standard successful operation - `UCXL-201-CREATED` - Resource successfully created - `UCXL-202-ACCEPTED` - Request accepted for processing - `UCXL-204-NO_CONTENT` - Successful operation with no content ### Error Responses All error responses follow this structure: ```json { "error": { "code": "UCXL-400-INVALID_ADDRESS", "message": "Invalid UCXL address format", "details": { "field": "address", "provided_address": "invalid-address", "parse_error": "address must start with 'ucxl://'" }, "source": "ucxi-server", "path": "/ucxi/v1/get", "request_id": "20240128-143052-abc12def", "timestamp": "2024-01-28T14:30:52.123Z", "cause": { // Optional causal error chain } } } ``` #### Error Code Examples: - `UCXL-400-BAD_REQUEST` - General bad request - `UCXL-400-INVALID_ADDRESS` - UCXL address validation failed - `UCXL-400-INVALID_PAYLOAD` - Request payload validation failed - `UCXL-400-TEMPORAL_INVALID` - Invalid temporal segment - `UCXL-404-NOT_FOUND` - Resource not found - `UCXL-404-RESOLUTION_FAILED` - UCXL address resolution failed - `UCXL-405-METHOD_NOT_ALLOWED` - HTTP method not supported - `UCXL-422-UNPROCESSABLE` - Request valid but cannot be processed - `UCXL-422-NAVIGATION_FAILED` - Temporal navigation failed - `UCXL-500-INTERNAL_ERROR` - General server error - `UCXL-500-STORAGE_FAILED` - Storage operation failed - `UCXL-500-ANNOUNCE_FAILED` - Content announcement failed #### Role-Based Collaboration Error Codes: - `UCXL-400-INVALID_ROLE` - Invalid or unrecognized role specified - `UCXL-404-EXPERTISE_NOT_AVAILABLE` - Requested expertise not available - `UCXL-404-MENTORSHIP_UNAVAILABLE` - No mentors available for request - `UCXL-404-PROJECT_NOT_FOUND` - Specified project not found or inaccessible - `UCXL-408-COLLABORATION_TIMEOUT` - Collaboration request timed out - `UCXL-500-COLLABORATION_FAILED` - General collaboration system failure ## API Endpoints ### Content Operations #### GET /ucxi/v1/get Retrieve content by UCXL address. **Parameters:** - `address` (required): UCXL address to retrieve **Example Success Response:** ```json { "response": { "code": "UCXL-200-SUCCESS", "message": "Request completed successfully", "data": { "address": { "agent": "claude", "role": "developer", "project": "bzzz", "task": "api-standardization", "temporal_segment": {"type": "latest"}, "path": "" }, "content": { "data": "SGVsbG8gV29ybGQ=", "content_type": "text/plain", "metadata": {"author": "claude"}, "version": 1, "created_at": "2024-01-28T14:30:52.123Z", "updated_at": "2024-01-28T14:30:52.123Z" }, "source": "peer-123", "resolved": "2024-01-28T14:30:52.123Z", "ttl": "1h0m0s" }, "request_id": "20240128-143052-abc12def", "timestamp": "2024-01-28T14:30:52.123Z" } } ``` **Example Error Response:** ```json { "error": { "code": "UCXL-400-INVALID_ADDRESS", "message": "Invalid UCXL address format", "details": { "field": "address", "provided_address": "invalid-address", "parse_error": "address must start with 'ucxl://'" }, "source": "ucxi-server", "path": "/ucxi/v1/get", "request_id": "20240128-143052-abc12def", "timestamp": "2024-01-28T14:30:52.123Z" } } ``` #### PUT /ucxi/v1/put Store content at a UCXL address. **Parameters:** - `address` (required): UCXL address to store content at **Headers:** - `Content-Type`: MIME type of content - `X-Author`: Optional author identifier - `X-Meta-*`: Custom metadata headers **Body:** Raw content to store **Example Success Response:** ```json { "response": { "code": "UCXL-201-CREATED", "message": "Resource created successfully", "data": { "address": "ucxl://claude:developer@bzzz:api-standardization/*^", "key": "claude:developer@bzzz:api-standardization/*^", "stored": true, "content": { "size": 1024, "content_type": "text/plain", "author": "claude", "metadata": {"version": "1.0"} } }, "request_id": "20240128-143052-abc12def", "timestamp": "2024-01-28T14:30:52.123Z" } } ``` #### DELETE /ucxi/v1/delete Remove content at a UCXL address. **Parameters:** - `address` (required): UCXL address to delete **Example Success Response:** ```json { "response": { "code": "UCXL-200-SUCCESS", "message": "Request completed successfully", "data": { "address": "ucxl://claude:developer@bzzz:api-standardization/*^", "key": "claude:developer@bzzz:api-standardization/*^", "deleted": true }, "request_id": "20240128-143052-abc12def", "timestamp": "2024-01-28T14:30:52.123Z" } } ``` ### Discovery Operations #### POST /ucxi/v1/announce Announce content availability on the network. **Request Body:** ```json { "address": "ucxl://claude:developer@bzzz:api-standardization/*^", "content": { "data": "SGVsbG8gV29ybGQ=", "content_type": "text/plain", "metadata": {"author": "claude"}, "version": 1, "created_at": "2024-01-28T14:30:52.123Z", "updated_at": "2024-01-28T14:30:52.123Z" } } ``` **Example Success Response:** ```json { "response": { "code": "UCXL-200-SUCCESS", "message": "Request completed successfully", "data": { "address": "ucxl://claude:developer@bzzz:api-standardization/*^", "announced": true, "content_summary": { "size": 1024, "content_type": "text/plain", "version": 1 } }, "request_id": "20240128-143052-abc12def", "timestamp": "2024-01-28T14:30:52.123Z" } } ``` #### GET /ucxi/v1/discover Discover content matching a pattern. **Parameters:** - `pattern` (required): UCXL address pattern for discovery **Example Success Response:** ```json { "response": { "code": "UCXL-200-SUCCESS", "message": "Request completed successfully", "data": { "pattern": "ucxl://any:developer@bzzz:any/*^", "results": [ { "address": { "agent": "claude", "role": "developer", "project": "bzzz", "task": "api-standardization" }, "content": {...}, "source": "peer-123", "resolved": "2024-01-28T14:30:52.123Z" } ], "results_count": 1 }, "request_id": "20240128-143052-abc12def", "timestamp": "2024-01-28T14:30:52.123Z" } } ``` ### Temporal Operations #### POST /ucxi/v1/navigate Navigate through temporal versions of content. **Request Body:** ```json { "address": "ucxl://claude:developer@bzzz:api-standardization/*^", "temporal_segment": "~~5" } ``` **Example Success Response:** ```json { "response": { "code": "UCXL-200-SUCCESS", "message": "Request completed successfully", "data": { "address": "ucxl://claude:developer@bzzz:api-standardization/*^", "temporal_segment": "~~5", "navigation_result": { "current_version": 10, "target_version": 5, "available_versions": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10], "content": {...} } }, "request_id": "20240128-143052-abc12def", "timestamp": "2024-01-28T14:30:52.123Z" } } ``` ### Status and Health #### GET /ucxi/v1/health Basic health check endpoint. **Example Response:** ```json { "response": { "code": "UCXL-200-SUCCESS", "message": "Request completed successfully", "data": { "status": "healthy", "running": true, "timestamp": "2024-01-28T14:30:52.123Z", "server": { "port": 8080, "base_path": "/api" } }, "request_id": "20240128-143052-abc12def", "timestamp": "2024-01-28T14:30:52.123Z" } } ``` #### GET /ucxi/v1/status Comprehensive status and configuration information (Issue 010). Now includes role-based collaboration and HMMM integration status. **Example Response:** ```json { "response": { "code": "UCXL-200-SUCCESS", "message": "Request completed successfully", "data": { "server": { "port": 8080, "base_path": "/api", "running": true, "version": "2.0.0", "started_at": "2024-01-28T13:30:52.123Z" }, "ucxi": { "enabled": true, "endpoints": [ "/get", "/put", "/post", "/delete", "/announce", "/discover", "/navigate", "/health", "/status" ] }, "resolver": { "enabled": true, "operations": { "resolve_count": 1234, "announce_count": 567, "discover_count": 89 }, "performance": { "avg_resolve_time_ms": 45, "success_rate": 0.99 } }, "storage": { "enabled": true, "operations": { "store_count": 2345, "retrieve_count": 6789, "delete_count": 123 }, "cache": { "size": 1024, "hit_rate": 0.85, "miss_rate": 0.15 }, "performance": { "avg_store_time_ms": 12, "avg_retrieve_time_ms": 8 } }, "navigators": { "active_count": 5, "keys": [ "claude:developer@bzzz:api-standardization", "alice:admin@bzzz:deployment" ] }, "p2p": { "enabled": true, "announce_enabled": true, "discover_enabled": true }, "collaboration": { "enabled": true, "features": { "role_based_messaging": true, "expertise_routing": true, "mentorship_support": true, "project_coordination": true, "status_updates": true }, "pubsub": { "topics": { "bzzz_coordination": "bzzz/coordination/v1", "hmmm_meta_discussion": "hmmm/meta-discussion/v1", "context_feedback": "bzzz/context-feedback/v1" }, "dynamic_topics": { "role_based_enabled": true, "project_topics_enabled": true, "expertise_routing_enabled": true } }, "message_types": [ "role_announcement", "expertise_request", "expertise_response", "status_update", "work_allocation", "role_collaboration", "mentorship_request", "mentorship_response", "project_update", "deliverable_ready" ], "metrics": { "active_roles": 3, "active_projects": 2, "collaboration_events": 145 } }, "hmmm_integration": { "enabled": true, "adapter": { "version": "1.0.0", "raw_publish_enabled": true, "topic_auto_join": true }, "features": { "slurp_event_integration": true, "per_issue_rooms": true, "consensus_driven_events": true, "context_updates": true }, "topics": { "slurp_events": "hmmm/slurp-events/v1", "context_updates": "hmmm/context-updates/v1", "issue_discussions": "hmmm/issues/{issue_id}/v1" }, "message_types": [ "slurp_event_generated", "slurp_event_ack", "slurp_context_update", "meta_discussion", "coordination_request", "dependency_alert", "escalation_trigger" ], "metrics": { "slurp_events_generated": 42, "slurp_events_acknowledged": 40, "active_discussions": 3, "consensus_sessions": 8 } }, "metrics": { "timestamp": "2024-01-28T14:30:52.123Z", "uptime_seconds": 3600 } }, "request_id": "20240128-143052-abc12def", "timestamp": "2024-01-28T14:30:52.123Z" } } ``` ### Role-Based Collaboration #### GET /ucxi/v1/collaboration Query role-based collaboration system status and active sessions. **Parameters:** - `role` (optional): Filter by specific role - `project` (optional): Filter by project ID - `expertise` (optional): Filter by expertise area **Example Success Response:** ```json { "response": { "code": "UCXL-200-SUCCESS", "message": "Request completed successfully", "data": { "system": { "enabled": true, "features": { "role_based_messaging": true, "expertise_routing": true, "mentorship_support": true, "project_coordination": true } }, "active_sessions": [ { "type": "expertise_request", "from_role": "junior_developer", "required_expertise": ["api_design", "error_handling"], "project_id": "bzzz", "thread_id": "thread-123", "participants": ["claude", "alice"], "status": "active", "created_at": "2024-01-28T14:20:52.123Z" }, { "type": "project_update", "from_role": "tech_lead", "project_id": "bzzz", "deliverable": "api_standardization", "status": "in_progress", "progress": 75, "created_at": "2024-01-28T14:25:52.123Z" } ], "filters_applied": { "role": null, "project": null, "expertise": null } }, "request_id": "20240128-143052-abc12def", "timestamp": "2024-01-28T14:30:52.123Z" } } ``` #### POST /ucxi/v1/collaboration Initiate a role-based collaboration session. **Request Body:** ```json { "type": "expertise_request", "from_role": "junior_developer", "to_roles": ["senior_developer", "tech_lead"], "required_expertise": ["api_design", "error_handling"], "project_id": "bzzz", "priority": "medium", "data": { "context": "Working on UCXI API standardization", "specific_question": "How to handle nested error chains in UCXL responses?" } } ``` **Example Success Response:** ```json { "response": { "code": "UCXL-201-CREATED", "message": "Resource created successfully", "data": { "collaboration_initiated": true, "thread_id": "thread-expertise_request-1706452252", "type": "expertise_request", "from_role": "junior_developer", "to_roles": ["senior_developer", "tech_lead"], "required_expertise": ["api_design", "error_handling"], "project_id": "bzzz", "priority": "medium", "status": "initiated", "expected_response_time": "15m", "routing": "expertise_based", "created_at": "2024-01-28T14:30:52.123Z" }, "request_id": "20240128-143052-abc12def", "timestamp": "2024-01-28T14:30:52.123Z" } } ``` **Collaboration Types:** - `expertise_request`: Request help from experts in specific areas - `mentorship_request`: Request mentoring from senior roles - `project_update`: Broadcast project status updates - `status_update`: Share individual agent status updates - `work_allocation`: Assign work to specific roles - `deliverable_ready`: Announce completed deliverables **Example Error Response:** ```json { "error": { "code": "UCXL-404-EXPERTISE_NOT_AVAILABLE", "message": "No experts available for requested expertise areas", "details": { "requested_expertise": ["quantum_computing", "blockchain"], "suggestion": "Try requesting more general expertise or check available experts" }, "source": "ucxi-server", "path": "/ucxi/v1/collaboration", "request_id": "20240128-143052-abc12def", "timestamp": "2024-01-28T14:30:52.123Z" } } ``` ## Request Headers ### Standard Headers - `Content-Type`: MIME type of request body - `Authorization`: Authentication credentials (when required) ### UCXI-Specific Headers - `X-Request-ID`: Client-provided request identifier (optional, server generates if not provided) - `X-Author`: Content author identification - `X-Meta-*`: Custom metadata (for PUT operations) ### CORS Headers The server automatically includes CORS headers: - `Access-Control-Allow-Origin: *` - `Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS` - `Access-Control-Allow-Headers: Content-Type, Authorization, X-Author, X-Meta-*` ## Error Handling ### HTTP Status Codes The API uses standard HTTP status codes that map to UCXL codes: - 200: Success operations (UCXL-200-SUCCESS) - 201: Created resources (UCXL-201-CREATED) - 400: Client errors (UCXL-400-*) - 404: Not found (UCXL-404-*) - 405: Method not allowed (UCXL-405-METHOD_NOT_ALLOWED) - 422: Unprocessable (UCXL-422-*) - 500: Server errors (UCXL-500-*) ### Error Details Error responses include structured details in the `details` field: ```json { "error": { "code": "UCXL-400-INVALID_ADDRESS", "message": "Invalid UCXL address format", "details": { "field": "address", "provided_address": "invalid-address", "parse_error": "address must start with 'ucxl://'" }, "source": "ucxi-server", "path": "/ucxi/v1/get", "request_id": "20240128-143052-abc12def", "timestamp": "2024-01-28T14:30:52.123Z" } } ``` ### Validation Errors UCXL address validation errors provide detailed information: ```json { "error": { "code": "UCXL-400-INVALID_ADDRESS", "message": "UCXL address validation error in agent: agent cannot be empty (address: ucxl://:role@project:task/*^)", "details": { "field": "agent", "raw_address": "ucxl://:role@project:task/*^", "validation_message": "agent cannot be empty" }, "source": "ucxi-server", "path": "/ucxi/v1/get", "request_id": "20240128-143052-abc12def", "timestamp": "2024-01-28T14:30:52.123Z" } } ``` ## Usage Examples ### cURL Examples **Retrieve content:** ```bash curl -X GET "http://localhost:8080/ucxi/v1/get?address=ucxl://claude:developer@bzzz:api-standardization/*^" \ -H "X-Request-ID: my-request-123" ``` **Store content:** ```bash curl -X PUT "http://localhost:8080/ucxi/v1/put?address=ucxl://claude:developer@bzzz:api-standardization/*^" \ -H "Content-Type: text/plain" \ -H "X-Author: claude" \ -H "X-Meta-Version: 1.0" \ -H "X-Request-ID: my-request-124" \ -d "Hello, UCXL World!" ``` **Check status:** ```bash curl -X GET "http://localhost:8080/ucxi/v1/status" \ -H "X-Request-ID: my-request-125" ``` ### JavaScript Example ```javascript // UCXI API Client class UCXIClient { constructor(baseUrl) { this.baseUrl = baseUrl; } async get(address, requestId = null) { const headers = { 'Content-Type': 'application/json' }; if (requestId) { headers['X-Request-ID'] = requestId; } const response = await fetch( `${this.baseUrl}/ucxi/v1/get?address=${encodeURIComponent(address)}`, { headers } ); const result = await response.json(); if (!response.ok) { throw new Error(`UCXI Error ${result.error.code}: ${result.error.message}`); } return result.response.data; } async put(address, content, options = {}) { const headers = { 'Content-Type': options.contentType || 'text/plain' }; if (options.author) { headers['X-Author'] = options.author; } if (options.metadata) { for (const [key, value] of Object.entries(options.metadata)) { headers[`X-Meta-${key}`] = value; } } if (options.requestId) { headers['X-Request-ID'] = options.requestId; } const response = await fetch( `${this.baseUrl}/ucxi/v1/put?address=${encodeURIComponent(address)}`, { method: 'PUT', headers, body: content } ); const result = await response.json(); if (!response.ok) { throw new Error(`UCXI Error ${result.error.code}: ${result.error.message}`); } return result.response.data; } async status(requestId = null) { const headers = {}; if (requestId) { headers['X-Request-ID'] = requestId; } const response = await fetch( `${this.baseUrl}/ucxi/v1/status`, { headers } ); const result = await response.json(); if (!response.ok) { throw new Error(`UCXI Error ${result.error.code}: ${result.error.message}`); } return result.response.data; } } // Usage example const client = new UCXIClient('http://localhost:8080'); try { // Store content await client.put( 'ucxl://claude:developer@bzzz:api-standardization/*^', 'Hello, UCXL World!', { author: 'claude', metadata: { version: '1.0' }, requestId: 'example-request-1' } ); // Retrieve content const content = await client.get( 'ucxl://claude:developer@bzzz:api-standardization/*^', 'example-request-2' ); console.log('Retrieved content:', content); // Check status const status = await client.status('example-request-3'); console.log('Server status:', status); } catch (error) { console.error('UCXI API error:', error.message); } ``` ## Backward Compatibility The API maintains backward compatibility by: 1. Preserving the legacy `Response` structure alongside new UCXL formats 2. Supporting both old and new response formats during a transition period 3. Providing clear deprecation warnings for legacy formats 4. Maintaining existing endpoint paths and parameter names ## Migration Guide ### For API Consumers 1. **Update response parsing** to handle the new UCXL structure: ```javascript // Old way if (response.success) { const data = response.data; } // New way if (response.response) { const data = response.response.data; const code = response.response.code; } ``` 2. **Handle error responses** using the new structure: ```javascript // Old way if (!response.success) { console.error(response.error); } // New way if (response.error) { console.error(`${response.error.code}: ${response.error.message}`); } ``` 3. **Use request IDs** for better tracing: ```javascript headers['X-Request-ID'] = generateRequestId(); ``` ### For Server Implementations 1. **Update response builders** to use UCXL formats 2. **Implement proper status endpoints** with comprehensive metrics 3. **Add request ID handling** throughout the middleware chain 4. **Update error handling** to provide structured error details ## Testing The implementation includes comprehensive integration tests covering: - UCXL response format validation - Error handling and status codes - Status endpoint functionality - Invalid address handling - Performance benchmarks Run tests with: ```bash go test -v ./pkg/ucxi/... ``` Run benchmarks with: ```bash go test -bench=. ./pkg/ucxi/... ``` ## Implementation Notes 1. **Request IDs** are automatically generated if not provided by the client 2. **CORS** is enabled by default for web client compatibility 3. **Content validation** is performed at the UCXL address level 4. **Error chaining** is supported via the `cause` field in error responses 5. **Status endpoint** provides real-time metrics and configuration details 6. **Performance metrics** are tracked and exposed through the status endpoint This standardization ensures consistent, traceable, and comprehensive API interactions across the UCXI system while maintaining backward compatibility and providing rich operational visibility.