🚀 Complete BZZZ Issue Resolution - All 17 Issues Solved
Comprehensive multi-agent implementation addressing all issues from INDEX.md: ## Core Architecture & Validation - ✅ Issue 001: UCXL address validation at all system boundaries - ✅ Issue 002: Fixed search parsing bug in encrypted storage - ✅ Issue 003: Wired UCXI P2P announce and discover functionality - ✅ Issue 011: Aligned temporal grammar and documentation - ✅ Issue 012: SLURP idempotency, backpressure, and DLQ implementation - ✅ Issue 013: Linked SLURP events to UCXL decisions and DHT ## API Standardization & Configuration - ✅ Issue 004: Standardized UCXI payloads to UCXL codes - ✅ Issue 010: Status endpoints and configuration surface ## Infrastructure & Operations - ✅ Issue 005: Election heartbeat on admin transition - ✅ Issue 006: Active health checks for PubSub and DHT - ✅ Issue 007: DHT replication and provider records - ✅ Issue 014: SLURP leadership lifecycle and health probes - ✅ Issue 015: Comprehensive monitoring, SLOs, and alerts ## Security & Access Control - ✅ Issue 008: Key rotation and role-based access policies ## Testing & Quality Assurance - ✅ Issue 009: Integration tests for UCXI + DHT encryption + search - ✅ Issue 016: E2E tests for HMMM → SLURP → UCXL workflow ## HMMM Integration - ✅ Issue 017: HMMM adapter wiring and comprehensive testing ## Key Features Delivered: - Enterprise-grade security with automated key rotation - Comprehensive monitoring with Prometheus/Grafana stack - Role-based collaboration with HMMM integration - Complete API standardization with UCXL response formats - Full test coverage with integration and E2E testing - Production-ready infrastructure monitoring and alerting All solutions include comprehensive testing, documentation, and production-ready implementations. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
anthonyrawlins
914
docs/UCXI_API_STANDARDIZATION.md
Normal file
914
docs/UCXI_API_STANDARDIZATION.md
Normal file
@@ -0,0 +1,914 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user