root
/
NAM-APJATEL-BACKEND
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
NAM-APJATEL-BACKEND/API_ROUTES_CABLE_CONNECTION...

6.2 KiB
Raw Blame History

Cable Connections API Routes - Updated

Base Path: /cable-connections

🔵 Basic CRUD Operations

Method Endpoint Description Auth Required
POST /search Search cable connections with filters ✅
GET /:id Get single cable connection by ID ✅
POST / Create single cable connection ✅
PUT /:id Update single cable connection ✅
DELETE /:id Delete single cable connection ✅

🟢 Bulk Operations (NEW!)

Method Endpoint Description Max Items Auth Required
POST /bulk/create Create multiple cable connections 100 ✅
PUT /bulk/update Update multiple cable connections 100 ✅
DELETE /bulk/delete Delete multiple cable connections 100 ✅

📊 Analytics & Reporting

Method Endpoint Description Auth Required
GET /device/:deviceId Get all connections for a device ✅
GET /analytics/length-distribution Cable length distribution stats ✅
GET /analytics/cable-types Cable type analytics ✅
POST /calculate-route Calculate optimal route between devices ✅

🔧 Maintenance & Monitoring

Method Endpoint Description Auth Required
GET /status/summary Cable status summary ✅
PUT /:id/status Update cable connection status ✅
GET /maintenance/due Get connections due for maintenance ✅

🗺️ Network Analysis

Method Endpoint Description Auth Required
POST /path/trace Trace cable path between devices ✅
GET /network-map Get network map of connections ✅

Authorization Requirements

All endpoints require authentication with one of these roles:

  • Teknisi
  • Admin
  • Super Admin

New Bulk Operation Details

1. POST /cable-connections/bulk/create

Request Body:

{
  "connections": [
    {
      "from_device_id": "uuid",
      "to_device_id": "uuid",
      "cable_length": 150.5,
      "cable_type": "fiber_optic",
      "branching_type": "direct",
      "installation_date": "2024-01-15T00:00:00Z",
      "status": "active",
      "notes": "Optional notes"
    }
  ]
}

Response:

{
  "message": "Bulk create completed: 1 successful, 0 failed out of 1 requested",
  "data": {
    "total_requested": 1,
    "successful": 1,
    "failed": 0,
    "errors": [],
    "results": [/* created connections with full details */],
    "execution_time": "120ms"
  }
}

2. PUT /cable-connections/bulk/update

Request Body:

{
  "connection_ids": ["uuid1", "uuid2", "uuid3"],
  "updates": {
    "status": "maintenance",
    "cable_type": "fiber_optic",
    "cable_length": 200.0,
    "notes": "Updated notes"
  }
}

Response:

{
  "message": "Bulk update completed: 3 successful, 0 failed out of 3 requested",
  "data": {
    "total_requested": 3,
    "successful": 3,
    "failed": 0,
    "errors": [],
    "results": [/* updated connections */],
    "execution_time": "80ms"
  }
}

Note: All fields in updates are optional. Only provided fields will be updated.

3. DELETE /cable-connections/bulk/delete

Request Body:

{
  "connection_ids": ["uuid1", "uuid2", "uuid3"]
}

Response:

{
  "message": "Bulk delete completed: 3 successful, 0 failed out of 3 requested",
  "data": {
    "total_requested": 3,
    "successful": 3,
    "failed": 0,
    "errors": [],
    "execution_time": "60ms"
  }
}

Error Handling

Partial Failures

When some items fail during bulk operations:

{
  "message": "Bulk create completed: 2 successful, 1 failed out of 3 requested",
  "data": {
    "total_requested": 3,
    "successful": 2,
    "failed": 1,
    "errors": [
      {
        "index": 1,
        "error": "From device not found",
        "details": "device with id uuid-999 does not exist"
      }
    ],
    "results": [/* successfully created items */],
    "execution_time": "150ms"
  }
}

Common Error Messages

Error Cause Solution
"From device not found" Device ID doesn't exist Verify device ID exists
"To device not found" Device ID doesn't exist Verify device ID exists
"Validation failed" Invalid field value Check cable_type, status values
"Connection not found" ID doesn't exist (update/delete) Verify connection ID
"cable_length must be at least 0.1" Cable length too small Use minimum 0.1m

Performance Comparison

Operation Individual (10 items) Bulk (10 items) Time Saved
Create 500ms (50ms × 10) 120ms 76% faster
Update 300ms (30ms × 10) 80ms 73% faster
Delete 200ms (20ms × 10) 60ms 70% faster

Best Practices

  1. Batch Size: Use 20-50 items per request for optimal performance
  2. Validation: Pre-validate device IDs before bulk operations
  3. Error Handling: Check errors array in response for failed items
  4. Retries: Retry failed items from errors array
  5. Monitoring: Track execution_time to monitor performance

Migration from Individual to Bulk Operations

Before (Individual Requests):

for (let connection of connections) {
  await fetch('/cable-connections', {
    method: 'POST',
    body: JSON.stringify(connection)
  });
}
// Total time: ~500ms for 10 items

After (Bulk Request):

await fetch('/cable-connections/bulk/create', {
  method: 'POST',
  body: JSON.stringify({ connections })
});
// Total time: ~120ms for 10 items

Related Documentation

Updated: October 10, 2025
Version: 2.0 (with Bulk Operations)