geutebruck/API_ENDPOINTS_GUIDE.md

# Action Mappings REST API - Complete Guide

## Overview

The REST API now provides comprehensive access to action mappings from GeViSoft .set files. You can access all endpoints via **Swagger UI** at: `http://localhost:8000/docs`

## Authentication

All endpoints require authentication:
- **Username:** `admin`
- **Password:** `admin123`

Click the **"Authorize"** button in Swagger UI to log in.

## Available Endpoints

### 1. GET /api/v1/configuration/action-mappings/export

**Get all action mappings (READ)**

Returns complete list of all action mappings with structured format including parameters.

**Authentication:** Viewer role (all users)

**Response Format:**
```json
{
  "total_mappings": 51,
  "mappings_with_parameters": 11,
  "mappings": [
    {
      "id": 1,
      "offset": 252173,
      "name": null,
      "input_actions": [],
      "output_actions": [
        {
          "action": "CrossSwitch C_101027 -> M",
          "parameters": {
            "SwitchMode": "True",
            "VideoInput": "101027",
            "VideoOutput": ""
          }
        },
        {
          "action": "GSC ViewerConnectLive V <- C",
          "parameters": {}
        }
      ]
    }
  ]
}
```

**Use Case:**
- Display all mappings in your frontend
- Export to Excel/CSV
- Analysis and reporting

---

### 2. GET /api/v1/configuration/action-mappings/{mapping_id}

**Get single mapping by ID (READ)**

Retrieve details of a specific action mapping.

**Authentication:** Viewer role

**Path Parameters:**
- `mapping_id`: Integer (1-based index, e.g., 1 = first mapping, 2 = second mapping)

**Example Request:**
```
GET /api/v1/configuration/action-mappings/5
```

**Response:**
```json
{
  "id": 5,
  "offset": 253586,
  "name": null,
  "input_actions": [],
  "output_actions": [
    {
      "action": "GSC warning: demo mode for 80 min",
      "parameters": {}
    }
  ]
}
```

**Use Case:**
- View details of specific mapping
- Editing preparation
- Debugging

---

### 3. POST /api/v1/configuration/action-mappings

**Create new mapping (CREATE)** ⚠️ Coming Soon

Add a new action mapping to the configuration.

**Authentication:** Administrator role

**Request Body:**
```json
{
  "name": "Switch Camera 101027",
  "output_actions": [
    {
      "action": "CrossSwitch C_101027 -> M",
      "parameters": {
        "SwitchMode": "True",
        "VideoInput": "101027"
      }
    }
  ]
}
```

**Status:** HTTP 501 Not Implemented
**Reason:** Requires .set file writer implementation (planned for next phase)

---

### 4. PUT /api/v1/configuration/action-mappings/{mapping_id}

**Update existing mapping (UPDATE)** ⚠️ Coming Soon

Modify an existing action mapping.

**Authentication:** Administrator role

**Path Parameters:**
- `mapping_id`: ID of mapping to update

**Request Body** (all fields optional):
```json
{
  "output_actions": [
    {
      "action": "CrossSwitch C_101027 -> M",
      "parameters": {
        "SwitchMode": "True",
        "VideoInput": "101027",
        "VideoOutput": "2"
      }
    }
  ]
}
```

**Status:** HTTP 501 Not Implemented

---

### 5. DELETE /api/v1/configuration/action-mappings/{mapping_id}

**Delete mapping (DELETE)** ⚠️ Coming Soon

Remove an action mapping from configuration.

**Authentication:** Administrator role

**Path Parameters:**
- `mapping_id`: ID of mapping to delete

**Status:** HTTP 501 Not Implemented

---

### 6. POST /api/v1/configuration/action-mappings/bulk-import

**Bulk import from Excel/CSV (CREATE MANY)** ⚠️ Coming Soon

Import multiple action mappings at once.

**Authentication:** Administrator role

**Request Body:**
```json
{
  "mappings": [
    {
      "name": "Mapping 1",
      "output_actions": [
        {
          "action": "Action1",
          "parameters": {"param1": "value1"}
        }
      ]
    },
    {
      "name": "Mapping 2",
      "output_actions": [
        {
          "action": "Action2",
          "parameters": {}
        }
      ]
    }
  ],
  "replace_existing": false
}
```

**Response:**
```json
{
  "success": true,
  "message": "Successfully imported 100 action mappings",
  "imported_count": 100,
  "failed_count": 0,
  "errors": []
}
```

**Status:** HTTP 501 Not Implemented

---

## Current Status

### ✅ Fully Functional
- **GET /action-mappings/export** - Read all mappings
- **GET /action-mappings/{id}** - Read single mapping

### ⏳ Planned (Next Phase)
- **POST /action-mappings** - Create single mapping
- **PUT /action-mappings/{id}** - Update mapping
- **DELETE /action-mappings/{id}** - Delete mapping
- **POST /action-mappings/bulk-import** - Bulk import

## Frontend Integration Recommendations

### Phase 1: Read-Only Interface (Available Now)

Build your frontend to:

1. **Display all mappings**
   ```javascript
   // Fetch all mappings
   GET /api/v1/configuration/action-mappings/export

   // Display in table/grid
   - Column: ID
   - Column: Actions (list)
   - Column: Parameters (expandable)
   - Column: Offset (for debugging)
   ```

2. **View details**
   ```javascript
   // User clicks on mapping
   GET /api/v1/configuration/action-mappings/{id}

   // Show modal/detail view with:
   - All actions
   - All parameters
   - Formatted display
   ```

3. **Export to Excel**
   ```javascript
   // Get all mappings
   const data = await fetch('/api/v1/configuration/action-mappings/export')

   // Convert to Excel using library (e.g., xlsx, exceljs)
   // Each mapping = 1 row
   // Columns: ID, Actions (comma-separated), Parameters (JSON)
   ```

### Phase 2: Full CRUD (Coming Soon)

Once the .set file writer is implemented:

1. **Manual Add**
   ```javascript
   // User fills form
   POST /api/v1/configuration/action-mappings
   Body: { name, output_actions }
   ```

2. **Edit**
   ```javascript
   // User modifies mapping
   PUT /api/v1/configuration/action-mappings/{id}
   Body: { output_actions }
   ```

3. **Delete**
   ```javascript
   DELETE /api/v1/configuration/action-mappings/{id}
   ```

4. **Bulk Import from Excel**
   ```javascript
   // User uploads Excel file
   // Parse Excel rows into JSON array
   // Post to bulk import endpoint
   POST /api/v1/configuration/action-mappings/bulk-import
   Body: { mappings: [...], replace_existing: false }
   ```

## Example Excel Import Workflow

### Excel Format

| ID | Name | Action 1 | Param 1 Name | Param 1 Value | Action 2 | Param 2 Name | Param 2 Value |
|----|------|----------|--------------|---------------|----------|--------------|---------------|
| 1 | Switch Cam 1 | CrossSwitch C_101027 -> M | SwitchMode | True | ViewerConnect | ClientID | 123 |
| 2 | Switch Cam 2 | CrossSwitch C_101028 -> M | SwitchMode | True | ViewerConnect | ClientID | 124 |

### Frontend Processing

```javascript
async function importExcel(file) {
  // 1. Parse Excel (using library like xlsx)
  const workbook = XLSX.read(await file.arrayBuffer());
  const sheet = workbook.Sheets[workbook.SheetNames[0]];
  const rows = XLSX.utils.sheet_to_json(sheet);

  // 2. Convert to API format
  const mappings = rows.map(row => ({
    name: row.Name,
    output_actions: [
      {
        action: row['Action 1'],
        parameters: {
          [row['Param 1 Name']]: row['Param 1 Value']
        }
      }
    ]
  }));

  // 3. Post to API
  const response = await fetch('/api/v1/configuration/action-mappings/bulk-import', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({
      mappings,
      replace_existing: false
    })
  });

  const result = await response.json();
  console.log(`Imported: ${result.imported_count}, Failed: ${result.failed_count}`);
}
```

## Testing in Swagger UI

1. Open: `http://localhost:8000/docs`

2. Click **"Authorize"**
   - Username: `admin`
   - Password: `admin123`

3. Try the **GET** endpoints:
   - Expand `GET /api/v1/configuration/action-mappings/export`
   - Click "Try it out"
   - Click "Execute"
   - See all 51+ mappings with parameters!

4. Try single mapping:
   - Expand `GET /api/v1/configuration/action-mappings/{mapping_id}`
   - Click "Try it out"
   - Enter `1` for mapping_id
   - Click "Execute"
   - See first mapping details

5. Try CREATE (will show 501):
   - Expand `POST /api/v1/configuration/action-mappings`
   - Click "Try it out"
   - See example request body
   - Click "Execute"
   - Get 501 Not Implemented (expected - coming soon!)

## Next Steps

### Immediate (You Can Do Now)

✅ Build frontend that:
- Displays all mappings (GET /export)
- Shows mapping details (GET /{id})
- Exports to Excel for editing
- Plans Excel import format

### Coming Soon (I Will Implement)

🔧 C# .set file writer to enable:
- POST /action-mappings (create)
- PUT /action-mappings/{id} (update)
- DELETE /action-mappings/{id} (delete)
- POST /action-mappings/bulk-import (Excel import)

### Future Expansion

📈 Additional configuration sections:
- Cameras
- Monitors
- Digital I/O
- Alarms
- System settings

---

## API Schema Summary

All endpoints return structured data with:

```typescript
interface ActionMapping {
  id: number;              // Sequential ID (1-based)
  offset: number;          // Byte offset in .set file
  name?: string;           // Optional descriptive name
  input_actions: Action[]; // Trigger actions (currently empty)
  output_actions: Action[]; // Response actions (at least 1)
}

interface Action {
  action: string;                    // Action command
  parameters: Record<string, string>; // Parameter name-value pairs
}
```

---

**Ready to start building your frontend!** 🚀

All READ operations are fully functional. CREATE/UPDATE/DELETE coming in next phase once .set file writer is complete.