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:

```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.