geutebruck-api/docs/api-reference.md

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