bzzz/docs/UCXI_API_STANDARDIZATION.md

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "address": "ucxl://claude:developer@bzzz:api-standardization/*^",
  "temporal_segment": "~~5"
}

Example Success Response:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

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:

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:

curl -X GET "http://localhost:8080/ucxi/v1/status" \
  -H "X-Request-ID: my-request-125"

JavaScript Example

// 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:

   // 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:

   // 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:

   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:

go test -v ./pkg/ucxi/...

Run benchmarks with:

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.