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

17 KiB
Raw Blame History

Cable Connection Management API

This document provides comprehensive information about the Cable Connection Management API endpoints, which handle the physical cable infrastructure connections between network devices.

Overview

The Cable Connection API manages physical fiber optic cable connections between devices in the network infrastructure. It provides functionality for tracking cable installations, analyzing cable routes, monitoring cable health, and optimizing network connectivity.

Base URL

/api/v1/cable-connections

Authentication

All endpoints require authentication with roles: Teknisi, Admin, or Super Admin.

Endpoints

1. Search Cable Connections

POST /api/v1/cable-connections/search

Search and filter cable connections with pagination support.

Request Body

{
  "page": 1,
  "per_page": 10,
  "cable_type": "fiber_optic",
  "status": "active",
  "device_id": "550e8400-e29b-41d4-a716-446655440000",
  "min_length": 100.0,
  "max_length": 5000.0,
  "branching_type": "direct",
  "installation_date_from": "2023-01-01T00:00:00Z",
  "installation_date_to": "2024-12-31T23:59:59Z",
  "sort_by": "cable_length",
  "sort_direction": "asc",
  "region": "Jawa Barat"
}

Response

{
  "status": {
    "code": 200,
    "description": "Success"
  },
  "data": {
    "connections": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "from_device_id": "550e8400-e29b-41d4-a716-446655440001",
        "to_device_id": "550e8400-e29b-41d4-a716-446655440002",
        "cable_length": 1250.5,
        "cable_type": "fiber_optic",
        "branching_type": "direct",
        "installation_date": "2023-06-15T08:30:00Z",
        "status": "active",
        "status_color": "#28a745",
        "created_at": "2023-06-10T10:00:00Z",
        "updated_at": "2023-06-15T08:30:00Z",
        "from_device": {
          "id": "550e8400-e29b-41d4-a716-446655440001",
          "device_code": "OTB-001",
          "device_type": "OTB",
          "latitude": -6.2088,
          "longitude": 106.8456,
          "province": "DKI Jakarta",
          "city": "Jakarta Pusat"
        },
        "to_device": {
          "id": "550e8400-e29b-41d4-a716-446655440002",
          "device_code": "ODP-001",
          "device_type": "ODP",
          "latitude": -6.2188,
          "longitude": 106.8556,
          "province": "DKI Jakarta",
          "city": "Jakarta Pusat"
        },
        "route_efficiency": 85.2,
        "estimated_cost": 12505000.0,
        "maintenance_due": false,
        "quality_score": 8.5
      }
    ],
    "total": 150,
    "page": 1,
    "per_page": 10,
    "search_params": {
      "cable_type": "fiber_optic",
      "status": "active",
      "min_length": 100.0,
      "max_length": 5000.0
    }
  }
}

2. Get Cable Connection by ID

GET /api/v1/cable-connections/{id}

Retrieve detailed information about a specific cable connection.

Path Parameters

  • id (UUID): Cable connection ID

Response

{
  "status": {
    "code": 200,
    "description": "Success"
  },
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "from_device_id": "550e8400-e29b-41d4-a716-446655440001",
    "to_device_id": "550e8400-e29b-41d4-a716-446655440002",
    "cable_length": 1250.5,
    "cable_type": "fiber_optic",
    "branching_type": "direct",
    "installation_date": "2023-06-15T08:30:00Z",
    "status": "active",
    "status_color": "#28a745",
    "created_at": "2023-06-10T10:00:00Z",
    "updated_at": "2023-06-15T08:30:00Z",
    "from_device": {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "device_code": "OTB-001",
      "device_type": "OTB",
      "latitude": -6.2088,
      "longitude": 106.8456,
      "province": "DKI Jakarta",
      "city": "Jakarta Pusat"
    },
    "to_device": {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "device_code": "ODP-001",
      "device_type": "ODP",
      "latitude": -6.2188,
      "longitude": 106.8556,
      "province": "DKI Jakarta",
      "city": "Jakarta Pusat"
    },
    "route_efficiency": 85.2,
    "estimated_cost": 12505000.0,
    "maintenance_due": false,
    "quality_score": 8.5
  }
}

3. Create Cable Connection

POST /api/v1/cable-connections

Create a new cable connection between two devices.

Request Body

{
  "from_device_id": "550e8400-e29b-41d4-a716-446655440001",
  "to_device_id": "550e8400-e29b-41d4-a716-446655440002",
  "cable_length": 1250.5,
  "cable_type": "fiber_optic",
  "branching_type": "direct",
  "installation_date": "2023-06-15T08:30:00Z",
  "status": "active",
  "notes": "Direct fiber connection for high-speed data transfer"
}

Response

{
  "status": {
    "code": 200,
    "description": "Success"
  },
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "from_device_id": "550e8400-e29b-41d4-a716-446655440001",
    "to_device_id": "550e8400-e29b-41d4-a716-446655440002",
    "cable_length": 1250.5,
    "cable_type": "fiber_optic",
    "branching_type": "direct",
    "installation_date": "2023-06-15T08:30:00Z",
    "status": "active",
    "status_color": "#28a745",
    "created_at": "2023-06-15T09:00:00Z",
    "updated_at": "2023-06-15T09:00:00Z"
  }
}

4. Update Cable Connection

PUT /api/v1/cable-connections/{id}

Update an existing cable connection.

Path Parameters

  • id (UUID): Cable connection ID

Request Body

{
  "cable_length": 1300.0,
  "status": "maintenance",
  "notes": "Updated length after field measurement"
}

Response

{
  "status": {
    "code": 200,
    "description": "Success"
  },
  "data": null
}

5. Delete Cable Connection

DELETE /api/v1/cable-connections/{id}

Delete a cable connection.

Path Parameters

  • id (UUID): Cable connection ID

Response

{
  "status": {
    "code": 200,
    "description": "Success"
  },
  "data": null
}

6. Get Device Cable Connections

GET /api/v1/cable-connections/device/{deviceId}

Get all cable connections for a specific device.

Path Parameters

  • deviceId (UUID): Device ID

Response

{
  "status": {
    "code": 200,
    "description": "Success"
  },
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "from_device_id": "550e8400-e29b-41d4-a716-446655440001",
      "to_device_id": "550e8400-e29b-41d4-a716-446655440002",
      "cable_length": 1250.5,
      "cable_type": "fiber_optic",
      "status": "active",
      "from_device": { /* device info */ },
      "to_device": { /* device info */ }
    }
  ]
}

7. Cable Length Distribution Analytics

GET /api/v1/cable-connections/analytics/length-distribution

Get cable length distribution analytics.

Query Parameters

  • cable_type (optional): Filter by cable type

Response

{
  "status": {
    "code": 200,
    "description": "Success"
  },
  "data": {
    "under_100m": 45,
    "from_100_500m": 120,
    "from_500_1000m": 85,
    "from_1_5km": 65,
    "above_5km": 15,
    "average_length": 850.5,
    "min_length": 25.0,
    "max_length": 12500.0,
    "total_connections": 330
  }
}

8. Cable Type Analytics

GET /api/v1/cable-connections/analytics/cable-types

Get cable type usage analytics.

Response

{
  "status": {
    "code": 200,
    "description": "Success"
  },
  "data": {
    "type_stats": [
      {
        "cable_type": "fiber_optic",
        "count": 250,
        "average_length": 950.5,
        "total_length": 237625.0,
        "percentage": 75.8
      },
      {
        "cable_type": "PTP_SFP_BLD",
        "count": 50,
        "average_length": 450.2,
        "total_length": 22510.0,
        "percentage": 15.2
      }
    ],
    "total_connections": 330,
    "total_length": 285420.0,
    "most_used_type": "fiber_optic",
    "least_used_type": "BB_MONEV"
  }
}

9. Calculate Optimal Route

POST /api/v1/cable-connections/calculate-route

Calculate the optimal route between two devices.

Request Body

{
  "from_device_id": "550e8400-e29b-41d4-a716-446655440001",
  "to_device_id": "550e8400-e29b-41d4-a716-446655440002",
  "cable_type": "fiber_optic",
  "max_hops": 3,
  "constraints": {
    "max_length": 5000.0,
    "preferred_types": ["fiber_optic", "PTP_SFP_BLD"],
    "avoid_devices": [],
    "require_active_only": true
  }
}

Response

{
  "status": {
    "code": 200,
    "description": "Success"
  },
  "data": {
    "from_device_id": "550e8400-e29b-41d4-a716-446655440001",
    "to_device_id": "550e8400-e29b-41d4-a716-446655440002",
    "direct_distance": 1200.5,
    "recommended_cable_length": 1440.6,
    "existing_connections": [],
    "alternative_routes": [
      {
        "route_id": "route-001",
        "path": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440010",
            "from_device_id": "550e8400-e29b-41d4-a716-446655440001",
            "to_device_id": "550e8400-e29b-41d4-a716-446655440003",
            "cable_length": 800.0,
            "cable_type": "fiber_optic",
            "status": "active",
            "hop_count": 1,
            "total_length": 800.0
          }
        ],
        "total_length": 1650.0,
        "hop_count": 2,
        "estimated_cost": 16500000.0,
        "reliability_score": 92.5,
        "recommendations": ["Consider direct connection for better performance"]
      }
    ],
    "recommendations": [
      "Direct connection recommended for optimal performance",
      "Consider fiber optic cable for high-speed requirements"
    ],
    "estimated_cost": 14406000.0,
    "complexity_score": 3.2
  }
}

10. Cable Status Summary

GET /api/v1/cable-connections/status/summary

Get summary of cable connection statuses.

Response

{
  "status": {
    "code": 200,
    "description": "Success"
  },
  "data": {
    "status_stats": [
      {
        "status": "active",
        "count": 280,
        "percentage": 84.8
      },
      {
        "status": "maintenance",
        "count": 35,
        "percentage": 10.6
      },
      {
        "status": "inactive",
        "count": 15,
        "percentage": 4.5
      }
    ],
    "total_connections": 330,
    "health_score": 84.8
  }
}

11. Update Cable Status

PUT /api/v1/cable-connections/{id}/status

Update the status of a cable connection.

Path Parameters

  • id (UUID): Cable connection ID

Request Body

{
  "status": "maintenance",
  "notes": "Scheduled maintenance for signal optimization",
  "reason": "Routine maintenance"
}

Response

{
  "status": {
    "code": 200,
    "description": "Success"
  },
  "data": null
}

12. Get Maintenance Due

GET /api/v1/cable-connections/maintenance/due

Get list of cable connections due for maintenance.

Query Parameters

  • days (optional, default: 30): Number of days to look ahead

Response

{
  "status": {
    "code": 200,
    "description": "Success"
  },
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "from_device_id": "550e8400-e29b-41d4-a716-446655440001",
      "to_device_id": "550e8400-e29b-41d4-a716-446655440002",
      "cable_length": 1250.5,
      "cable_type": "fiber_optic",
      "installation_date": "2022-06-15T08:30:00Z",
      "status": "active",
      "from_device_code": "OTB-001",
      "to_device_code": "ODP-001",
      "days_since_installation": 450,
      "maintenance_priority": "medium",
      "recommended_action": "Signal quality inspection"
    }
  ]
}

13. Trace Cable Path

POST /api/v1/cable-connections/path/trace

Trace the connection path between two devices.

Request Body

{
  "from_device_id": "550e8400-e29b-41d4-a716-446655440001",
  "to_device_id": "550e8400-e29b-41d4-a716-446655440002",
  "max_hops": 5,
  "path_type": "shortest"
}

Response

{
  "status": {
    "code": 200,
    "description": "Success"
  },
  "data": {
    "from_device_id": "550e8400-e29b-41d4-a716-446655440001",
    "to_device_id": "550e8400-e29b-41d4-a716-446655440002",
    "total_length": 2150.5,
    "hop_count": 3,
    "connection_path": [
      "550e8400-e29b-41d4-a716-446655440010",
      "550e8400-e29b-41d4-a716-446655440011",
      "550e8400-e29b-41d4-a716-446655440012"
    ],
    "path_details": [
      {
        "connection_id": "550e8400-e29b-41d4-a716-446655440010",
        "from_device": {
          "id": "550e8400-e29b-41d4-a716-446655440001",
          "device_code": "OTB-001",
          "device_type": "OTB",
          "latitude": -6.2088,
          "longitude": 106.8456
        },
        "to_device": {
          "id": "550e8400-e29b-41d4-a716-446655440003",
          "device_code": "JUNCTION-001",
          "device_type": "JUNCTION",
          "latitude": -6.2188,
          "longitude": 106.8556
        },
        "cable_length": 800.0,
        "cable_type": "fiber_optic",
        "status": "active",
        "signal_loss": 0.5,
        "segment_order": 1
      }
    ],
    "is_complete": true,
    "quality_score": 87.5
  }
}

14. Get Network Map

GET /api/v1/cable-connections/network-map

Get network map data with cable connections.

Query Parameters

  • device_type (optional): Filter by device type
  • cable_type (optional): Filter by cable type
  • region (optional): Filter by region

Response

{
  "status": {
    "code": 200,
    "description": "Success"
  },
  "data": {
    "connections": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "from_device_id": "550e8400-e29b-41d4-a716-446655440001",
        "to_device_id": "550e8400-e29b-41d4-a716-446655440002",
        "cable_length": 1250.5,
        "cable_type": "fiber_optic",
        "status": "active",
        "from_device_code": "OTB-001",
        "from_device_type": "OTB",
        "from_latitude": -6.2088,
        "from_longitude": 106.8456,
        "to_device_code": "ODP-001",
        "to_device_type": "ODP",
        "to_latitude": -6.2188,
        "to_longitude": 106.8556
      }
    ],
    "stats": {
      "total_connections": 330,
      "average_length": 850.5,
      "total_length": 280665.0,
      "unique_devices": 185
    },
    "bounds": {
      "north_east": {
        "latitude": -6.1088,
        "longitude": 106.9456
      },
      "south_west": {
        "latitude": -6.3088,
        "longitude": 106.7456
      }
    }
  }
}

Error Responses

400 Bad Request

{
  "status": {
    "code": 400,
    "description": "Bad Request"
  },
  "error": "Validation error: cable_length must be greater than 0"
}

404 Not Found

{
  "status": {
    "code": 404,
    "description": "Not Found"
  },
  "error": "Cable connection not found"
}

401 Unauthorized

{
  "status": {
    "code": 401,
    "description": "Unauthorized"
  },
  "error": "Authentication required"
}

403 Forbidden

{
  "status": {
    "code": 403,
    "description": "Forbidden"
  },
  "error": "Insufficient permissions"
}

Data Models

Cable Connection

  • id: UUID - Unique identifier
  • from_device_id: UUID - Source device ID
  • to_device_id: UUID - Destination device ID
  • cable_length: Float - Cable length in meters
  • cable_type: String - Type of cable (fiber_optic, PTP_SFP_BLD, etc.)
  • branching_type: String - Type of branching connection
  • installation_date: DateTime - When the cable was installed
  • status: String - Connection status (active, inactive, maintenance, planned)
  • created_at: DateTime - Record creation timestamp
  • updated_at: DateTime - Last update timestamp

Cable Types

  • fiber_optic: Standard fiber optic cable
  • PTP_SFP_BLD: Point-to-point SFP building cable
  • PTP_SFP_DUPLEX: Point-to-point SFP duplex cable
  • BB_MONEV: Backbone monitoring cable
  • drop_cable: Drop cable for last-mile connections

Status Values

  • active: Connection is operational
  • inactive: Connection is not in use
  • maintenance: Connection is under maintenance
  • planned: Connection is planned but not yet installed

Use Cases

1. Cable Installation Planning

Use the optimal route calculation and network map endpoints to plan new cable installations efficiently.

2. Network Maintenance

Monitor cable health using analytics endpoints and schedule maintenance based on installation dates and quality scores.

3. Network Optimization

Analyze cable length distribution and route efficiency to identify optimization opportunities.

4. Troubleshooting

Use path tracing to diagnose connectivity issues and identify problematic network segments.

5. Asset Management

Track all cable assets with detailed information about length, type, and installation details.

Best Practices

  1. Cable Length Validation: Always validate that cable length is reasonable compared to device distance
  2. Route Optimization: Use optimal route calculation before installing new cables
  3. Regular Maintenance: Monitor maintenance due dates and quality scores
  4. Status Management: Keep cable statuses updated for accurate network visibility
  5. Documentation: Include detailed notes when creating or updating cable connections