731 lines
17 KiB
Markdown
731 lines
17 KiB
Markdown
# 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
|
|
```json
|
|
{
|
|
"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
|
|
```json
|
|
{
|
|
"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
|
|
```json
|
|
{
|
|
"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
|
|
```json
|
|
{
|
|
"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
|
|
```json
|
|
{
|
|
"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
|
|
```json
|
|
{
|
|
"cable_length": 1300.0,
|
|
"status": "maintenance",
|
|
"notes": "Updated length after field measurement"
|
|
}
|
|
```
|
|
|
|
#### Response
|
|
```json
|
|
{
|
|
"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
|
|
```json
|
|
{
|
|
"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
|
|
```json
|
|
{
|
|
"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
|
|
```json
|
|
{
|
|
"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
|
|
```json
|
|
{
|
|
"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
|
|
```json
|
|
{
|
|
"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
|
|
```json
|
|
{
|
|
"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
|
|
```json
|
|
{
|
|
"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
|
|
```json
|
|
{
|
|
"status": "maintenance",
|
|
"notes": "Scheduled maintenance for signal optimization",
|
|
"reason": "Routine maintenance"
|
|
}
|
|
```
|
|
|
|
#### Response
|
|
```json
|
|
{
|
|
"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
|
|
```json
|
|
{
|
|
"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
|
|
```json
|
|
{
|
|
"from_device_id": "550e8400-e29b-41d4-a716-446655440001",
|
|
"to_device_id": "550e8400-e29b-41d4-a716-446655440002",
|
|
"max_hops": 5,
|
|
"path_type": "shortest"
|
|
}
|
|
```
|
|
|
|
#### Response
|
|
```json
|
|
{
|
|
"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
|
|
```json
|
|
{
|
|
"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
|
|
```json
|
|
{
|
|
"status": {
|
|
"code": 400,
|
|
"description": "Bad Request"
|
|
},
|
|
"error": "Validation error: cable_length must be greater than 0"
|
|
}
|
|
```
|
|
|
|
### 404 Not Found
|
|
```json
|
|
{
|
|
"status": {
|
|
"code": 404,
|
|
"description": "Not Found"
|
|
},
|
|
"error": "Cable connection not found"
|
|
}
|
|
```
|
|
|
|
### 401 Unauthorized
|
|
```json
|
|
{
|
|
"status": {
|
|
"code": 401,
|
|
"description": "Unauthorized"
|
|
},
|
|
"error": "Authentication required"
|
|
}
|
|
```
|
|
|
|
### 403 Forbidden
|
|
```json
|
|
{
|
|
"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 |