Phase 8: MVP Polish - COMPLETE (T075-T084)
🎉 MVP v1.0.0 COMPLETE! 🎉 Final polishing phase with comprehensive documentation and enhanced monitoring: **Enhanced Monitoring:** - Enhanced health check endpoint with component-level status - Database connectivity check (PostgreSQL) - Redis connectivity check - SDK Bridge connectivity check (gRPC) - Overall status (healthy/degraded) - Metrics endpoint with route counts and feature flags - Updated root endpoint with metrics link **Comprehensive Documentation:** - API Reference (docs/api-reference.md) - Complete endpoint documentation - Request/response examples - Authentication guide - Error responses - RBAC table - Deployment Guide (docs/deployment.md) - Prerequisites and system requirements - Installation instructions - Database setup and migrations - Production deployment (Windows Service/IIS/Docker) - Security hardening - Monitoring and alerts - Backup and recovery - Troubleshooting - Usage Guide (docs/usage-guide.md) - Practical examples with curl - Common operations - Use case scenarios - Python and C# client examples - Postman testing guide - Best practices - Release Notes (RELEASE_NOTES.md) - Complete MVP feature list - Architecture overview - Technology stack - Installation quick start - Testing coverage - Security considerations - Known limitations - Future roadmap **MVP Deliverables:** ✅ 21 API endpoints ✅ 84 tasks completed ✅ 213 test cases ✅ 3-tier architecture (API + SDK Bridge + GeViServer) ✅ JWT authentication with RBAC ✅ Cross-switching control (CORE FEATURE) ✅ Camera/monitor discovery ✅ Routing state management ✅ Audit logging ✅ Redis caching ✅ PostgreSQL persistence ✅ Comprehensive documentation **Core Functionality:** - Execute cross-switch (route camera to monitor) - Clear monitor (remove camera) - Query routing state (active routes) - Routing history with pagination - RBAC enforcement (Operator required for execution) **Out of Scope (Intentional):** ❌ Recording management ❌ Video analytics ❌ LPR/NPR ❌ PTZ control ❌ Live streaming 🚀 Ready for deployment and testing! 🚀 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Geutebruck API Developer
305
docs/api-reference.md
Normal file
305
docs/api-reference.md
Normal file
@@ -0,0 +1,305 @@
|
||||
# Geutebruck Cross-Switching API Reference
|
||||
|
||||
## Overview
|
||||
|
||||
REST API for Geutebruck GeViScope/GeViSoft cross-switching control. Route cameras to monitors via simple HTTP endpoints.
|
||||
|
||||
**Base URL**: `http://localhost:8000`
|
||||
**API Version**: 1.0.0
|
||||
**Authentication**: JWT Bearer tokens
|
||||
|
||||
## Quick Links
|
||||
|
||||
- **Interactive Docs**: http://localhost:8000/docs (Swagger UI)
|
||||
- **Alternative Docs**: http://localhost:8000/redoc (ReDoc)
|
||||
- **Health Check**: http://localhost:8000/health
|
||||
- **Metrics**: http://localhost:8000/metrics
|
||||
|
||||
---
|
||||
|
||||
## Authentication
|
||||
|
||||
### POST /api/v1/auth/login
|
||||
|
||||
Authenticate and receive JWT tokens.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"username": "admin",
|
||||
"password": "admin123"
|
||||
}
|
||||
```
|
||||
|
||||
**Response (200 OK):**
|
||||
```json
|
||||
{
|
||||
"access_token": "eyJhbGciOiJIUzI1NiIs...",
|
||||
"refresh_token": "eyJhbGciOiJIUzI1NiIs...",
|
||||
"token_type": "bearer",
|
||||
"expires_in": 3600,
|
||||
"user": {
|
||||
"id": "uuid",
|
||||
"username": "admin",
|
||||
"role": "administrator"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### POST /api/v1/auth/logout
|
||||
|
||||
Logout (blacklist token).
|
||||
|
||||
**Headers**: `Authorization: Bearer {access_token}`
|
||||
|
||||
**Response (200 OK):**
|
||||
```json
|
||||
{
|
||||
"message": "Successfully logged out"
|
||||
}
|
||||
```
|
||||
|
||||
### GET /api/v1/auth/me
|
||||
|
||||
Get current user information.
|
||||
|
||||
**Headers**: `Authorization: Bearer {access_token}`
|
||||
|
||||
---
|
||||
|
||||
## Cameras
|
||||
|
||||
### GET /api/v1/cameras
|
||||
|
||||
List all cameras.
|
||||
|
||||
**Headers**: `Authorization: Bearer {access_token}`
|
||||
**Required Role**: Viewer+
|
||||
|
||||
**Response (200 OK):**
|
||||
```json
|
||||
{
|
||||
"cameras": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "Entrance Camera",
|
||||
"description": "Main entrance",
|
||||
"has_ptz": true,
|
||||
"has_video_sensor": true,
|
||||
"status": "online"
|
||||
}
|
||||
],
|
||||
"total": 1
|
||||
}
|
||||
```
|
||||
|
||||
### GET /api/v1/cameras/{camera_id}
|
||||
|
||||
Get camera details.
|
||||
|
||||
**Headers**: `Authorization: Bearer {access_token}`
|
||||
**Required Role**: Viewer+
|
||||
|
||||
---
|
||||
|
||||
## Monitors
|
||||
|
||||
### GET /api/v1/monitors
|
||||
|
||||
List all monitors.
|
||||
|
||||
**Headers**: `Authorization: Bearer {access_token}`
|
||||
**Required Role**: Viewer+
|
||||
|
||||
**Response (200 OK):**
|
||||
```json
|
||||
{
|
||||
"monitors": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "Control Room Monitor 1",
|
||||
"description": "Main display",
|
||||
"status": "active",
|
||||
"current_camera_id": 5
|
||||
}
|
||||
],
|
||||
"total": 1
|
||||
}
|
||||
```
|
||||
|
||||
### GET /api/v1/monitors/filter/available
|
||||
|
||||
Get available (idle) monitors for cross-switching.
|
||||
|
||||
**Headers**: `Authorization: Bearer {access_token}`
|
||||
**Required Role**: Viewer+
|
||||
|
||||
---
|
||||
|
||||
## Cross-Switching (Core Functionality)
|
||||
|
||||
### POST /api/v1/crossswitch
|
||||
|
||||
**Execute cross-switch**: Route camera to monitor.
|
||||
|
||||
**Headers**: `Authorization: Bearer {access_token}`
|
||||
**Required Role**: **Operator+** (NOT Viewer)
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"camera_id": 1,
|
||||
"monitor_id": 1,
|
||||
"mode": 0
|
||||
}
|
||||
```
|
||||
|
||||
**Response (200 OK):**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Successfully switched camera 1 to monitor 1",
|
||||
"route": {
|
||||
"id": "uuid",
|
||||
"camera_id": 1,
|
||||
"monitor_id": 1,
|
||||
"executed_at": "2025-12-09T12:00:00Z",
|
||||
"executed_by": "uuid",
|
||||
"executed_by_username": "operator",
|
||||
"is_active": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### POST /api/v1/crossswitch/clear
|
||||
|
||||
**Clear monitor**: Remove camera from monitor.
|
||||
|
||||
**Headers**: `Authorization: Bearer {access_token}`
|
||||
**Required Role**: **Operator+**
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"monitor_id": 1
|
||||
}
|
||||
```
|
||||
|
||||
**Response (200 OK):**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Successfully cleared monitor 1",
|
||||
"monitor_id": 1
|
||||
}
|
||||
```
|
||||
|
||||
### GET /api/v1/crossswitch/routing
|
||||
|
||||
Get current routing state (active camera-to-monitor mappings).
|
||||
|
||||
**Headers**: `Authorization: Bearer {access_token}`
|
||||
**Required Role**: Viewer+
|
||||
|
||||
**Response (200 OK):**
|
||||
```json
|
||||
{
|
||||
"routes": [
|
||||
{
|
||||
"id": "uuid",
|
||||
"camera_id": 1,
|
||||
"monitor_id": 1,
|
||||
"executed_at": "2025-12-09T12:00:00Z",
|
||||
"executed_by_username": "operator",
|
||||
"is_active": true
|
||||
}
|
||||
],
|
||||
"total": 1
|
||||
}
|
||||
```
|
||||
|
||||
### GET /api/v1/crossswitch/history
|
||||
|
||||
Get routing history with pagination.
|
||||
|
||||
**Headers**: `Authorization: Bearer {access_token}`
|
||||
**Required Role**: Viewer+
|
||||
|
||||
**Query Parameters:**
|
||||
- `limit`: Max records (1-1000, default: 100)
|
||||
- `offset`: Skip records (default: 0)
|
||||
- `camera_id`: Filter by camera (optional)
|
||||
- `monitor_id`: Filter by monitor (optional)
|
||||
|
||||
---
|
||||
|
||||
## Authorization Roles
|
||||
|
||||
| Role | Cameras | Monitors | Cross-Switch | Clear Monitor | View Routing |
|
||||
|------|---------|----------|--------------|---------------|--------------|
|
||||
| **Viewer** | ✅ Read | ✅ Read | ❌ | ❌ | ✅ Read |
|
||||
| **Operator** | ✅ Read | ✅ Read | ✅ Execute | ✅ Execute | ✅ Read |
|
||||
| **Administrator** | ✅ Read | ✅ Read | ✅ Execute | ✅ Execute | ✅ Read |
|
||||
|
||||
---
|
||||
|
||||
## Error Responses
|
||||
|
||||
### 401 Unauthorized
|
||||
```json
|
||||
{
|
||||
"error": "Unauthorized",
|
||||
"message": "Authentication required"
|
||||
}
|
||||
```
|
||||
|
||||
### 403 Forbidden
|
||||
```json
|
||||
{
|
||||
"error": "Forbidden",
|
||||
"message": "Requires operator role or higher"
|
||||
}
|
||||
```
|
||||
|
||||
### 404 Not Found
|
||||
```json
|
||||
{
|
||||
"error": "Not Found",
|
||||
"detail": "Camera with ID 999 not found"
|
||||
}
|
||||
```
|
||||
|
||||
### 500 Internal Server Error
|
||||
```json
|
||||
{
|
||||
"error": "Internal Server Error",
|
||||
"detail": "Cross-switch operation failed: SDK Bridge connection timeout"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
Currently not implemented in MVP. Consider adding in production.
|
||||
|
||||
---
|
||||
|
||||
## Caching
|
||||
|
||||
- **Cameras**: Cached for 60 seconds in Redis
|
||||
- **Monitors**: Cached for 60 seconds in Redis
|
||||
- **Routing State**: Not cached (real-time from database)
|
||||
|
||||
Use `use_cache=false` query parameter to bypass cache.
|
||||
|
||||
---
|
||||
|
||||
## Audit Logging
|
||||
|
||||
All operations are logged to the `audit_logs` table:
|
||||
- Authentication attempts (success/failure)
|
||||
- Cross-switch executions
|
||||
- Monitor clear operations
|
||||
|
||||
Query audit logs via database or add dedicated endpoint in future.
|
||||
Reference in New Issue
Block a user