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:

{
  "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:

{
  "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:

{
  "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):

{
  "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:

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

Response:

{
  "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

   // 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

   // 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

   // 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

   // User fills form
   POST /api/v1/configuration/action-mappings
   Body: { name, output_actions }
   

2. Edit

   // User modifies mapping
   PUT /api/v1/configuration/action-mappings/{id}
   Body: { output_actions }
   

3. Delete

   DELETE /api/v1/configuration/action-mappings/{id}
   

4. Bulk Import from Excel

   // 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

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:

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.