The WiFi-DensePose API provides RESTful endpoints and WebSocket connections for real-time human pose estimation using WiFi CSI (Channel State Information) data. The API is built with FastAPI and supports both synchronous REST operations and real-time streaming via WebSockets.

- **Development**: `http://localhost:8000`

- **API Prefix**: `/api/v1`

- **Documentation**: `http://localhost:8000/docs`

Authentication is configurable via environment variables:

- When `ENABLE_AUTHENTICATION=true`, protected endpoints require JWT tokens

- Tokens can be passed via:

- Authorization header: `Bearer <token>`

- Query parameter: `?token=<token>`

- Cookie: `access_token`

Rate limiting is configurable and when enabled (`ENABLE_RATE_LIMITING=true`):

- Anonymous: 100 requests/hour

- Authenticated: 1000 requests/hour

- Admin: 10000 requests/hour

System health check with component status and metrics.

**Response Example:**

{

"status": "healthy",

"timestamp": "2025-06-09T16:00:00Z",

"uptime_seconds": 3600.0,

"components": {

"hardware": {...},

"pose": {...},

"stream": {...}

},

"system_metrics": {

"cpu": {"percent": 24.1, "count": 2},

"memory": {"total_gb": 7.75, "available_gb": 3.73},

"disk": {"total_gb": 31.33, "free_gb": 7.09}

}

}

Readiness check for load balancers.

Simple liveness check.

Detailed system metrics (requires auth).

Get current pose estimation from WiFi signals.

**Query Parameters:**

- `zone_ids`: List of zone IDs to analyze

- `confidence_threshold`: Minimum confidence (0.0-1.0)

- `max_persons`: Maximum persons to detect

- `include_keypoints`: Include keypoint data (default: true)

- `include_segmentation`: Include DensePose segmentation (default: false)

**Response Example:**

{

"timestamp": "2025-06-09T16:00:00Z",

"frame_id": "frame_123456",

"persons": [

{

"person_id": "0",

"confidence": 0.95,

"bounding_box": {"x": 0.1, "y": 0.2, "width": 0.3, "height": 0.6},

"keypoints": [...],

"zone_id": "zone_1",

"activity": "standing"

}

],

"zone_summary": {"zone_1": 1, "zone_2": 0},

"processing_time_ms": 45.2

}

Analyze pose data with custom parameters (requires auth).

Get occupancy for a specific zone.

Get occupancy summary for all zones.

Get recently detected activities.

**Query Parameters:**

- `zone_id`: Filter by zone

- `limit`: Maximum results (1-100)

Query historical pose data (requires auth).

**Request Body:**

{

"start_time": "2025-06-09T15:00:00Z",

"end_time": "2025-06-09T16:00:00Z",

"zone_ids": ["zone_1"],

"aggregation_interval": 300,

"include_raw_data": false

}

Get pose estimation statistics.

**Query Parameters:**

- `hours`: Hours of data to analyze (1-168)

Start system calibration (requires auth).

Get calibration status (requires auth).

Get streaming service status.

Start streaming service (requires auth).

Stop streaming service (requires auth).

List connected WebSocket clients (requires auth).

Disconnect specific client (requires auth).

Broadcast message to clients (requires auth).

Real-time pose data streaming.

**Query Parameters:**

- `zone_ids`: Comma-separated zone IDs

- `min_confidence`: Minimum confidence (0.0-1.0)

- `max_fps`: Maximum frames per second (1-60)

- `token`: Auth token (if authentication enabled)

**Message Types:**

- `connection_established`: Initial connection confirmation

- `pose_update`: Pose data updates

- `error`: Error messages

- `ping`/`pong`: Keep-alive

Real-time event streaming.

**Query Parameters:**

- `event_types`: Comma-separated event types

- `zone_ids`: Comma-separated zone IDs

- `token`: Auth token (if authentication enabled)

Root endpoint with API information.

Detailed API configuration.

Current API and service status.

API performance metrics (if enabled).

These endpoints are only available when `ENABLE_TEST_ENDPOINTS=true`:

Get current configuration (development only).

Reset services (development only).

All errors follow a consistent format:

{

"error": {

"code": 400,

"message": "Error description",

"type": "error_type"

}

}

Error types:

- `http_error`: HTTP-related errors

- `validation_error`: Request validation errors

- `authentication_error`: Authentication failures

- `rate_limit_exceeded`: Rate limit violations

- `internal_error`: Server errors

1. **Connect**: `ws://host/api/v1/stream/pose?params`

2. **Receive**: Connection confirmation message

3. **Send/Receive**: Bidirectional communication

4. **Disconnect**: Clean connection closure

All WebSocket messages use JSON format:

{

"type": "message_type",

"timestamp": "ISO-8601 timestamp",

"data": {...}

}

- `{"type": "ping"}`: Keep-alive ping

- `{"type": "update_config", "config": {...}}`: Update stream config

- `{"type": "get_status"}`: Request status

- `{"type": "disconnect"}`: Clean disconnect

- `{"type": "connection_established", ...}`: Connection confirmed

- `{"type": "pose_update", ...}`: Pose data update

- `{"type": "event", ...}`: Event notification

- `{"type": "pong"}`: Ping response

- `{"type": "error", "message": "..."}`: Error message

CORS is enabled with configurable origins:

- Development: Allow all origins (`*`)

- Production: Restrict to specific domains

The API includes security headers:

- `X-Content-Type-Options: nosniff`

- `X-Frame-Options: DENY`

- `X-XSS-Protection: 1; mode=block`

- `Referrer-Policy: strict-origin-when-cross-origin`

- `Content-Security-Policy: ...`

1. **Batch Requests**: Use zone summaries instead of individual zone queries

2. **WebSocket Streaming**: Adjust `max_fps` to reduce bandwidth

3. **Historical Data**: Use appropriate `aggregation_interval`

4. **Caching**: Results are cached when Redis is enabled

Use the provided test scripts:

- `scripts/test_api_endpoints.py`: Comprehensive endpoint testing

- `scripts/test_websocket_streaming.py`: WebSocket functionality testing

For production:

1. Set `ENVIRONMENT=production`

2. Enable authentication and rate limiting

3. Configure proper database (PostgreSQL)

4. Enable Redis for caching

5. Use HTTPS with valid certificates

6. Restrict CORS origins

7. Disable debug mode and test endpoints

8. Configure monitoring and logging

The API uses URL versioning:

- Current version: `v1`

- Base path: `/api/v1`

Future versions will be available at `/api/v2`, etc.