Merge branch 'segment' into 'main'

update segment serializer to handle path file upload. Remove unnecesary...

See merge request 701/netbox/cesnet_service_path_plugin!28

Author: jirivrany

README.md

@@ -228,6 +228,9 @@ The plugin provides comprehensive REST API and GraphQL support:
 - `/api/plugins/cesnet-service-path-plugin/service-paths/` - Service path management
 - `/api/plugins/cesnet-service-path-plugin/segments/{id}/geojson-api/` - Geographic data
 
+#### Example of segment with path file PATCH and POST 
+See [detailed example in docs](./docs/API_path.md).
+
 ### Geographic API Features
 
 - **Lightweight list serializers** for performance

cesnet_service_path_plugin/api/serializers/segment.py

@@ -10,9 +10,12 @@
 from cesnet_service_path_plugin.models.segment import Segment
 from cesnet_service_path_plugin.utils import export_segment_paths_as_geojson
 
+from cesnet_service_path_plugin.utils import process_path_data, determine_file_format_from_extension
+from django.core.exceptions import ValidationError as DjangoValidationError
+
 
 class SegmentSerializer(NetBoxModelSerializer):
-    """Default serializer Segment - excludes heavy geometry fields"""
+    """Default serializer Segment - now with file upload support"""
 
     url = serializers.HyperlinkedIdentityField(view_name="plugins-api:cesnet_service_path_plugin-api:segment-detail")
     provider = ProviderSerializer(required=True, nested=True)
@@ -22,60 +25,12 @@ class SegmentSerializer(NetBoxModelSerializer):
     location_b = LocationSerializer(required=True, nested=True)
     circuits = CircuitSerializer(required=False, many=True, nested=True)
 
-    # Only include lightweight path info
-    has_path_data = serializers.SerializerMethodField(read_only=True)
-
-    class Meta:
-        model = Segment
-        fields = (
-            "id",
-            "url",
-            "display",
-            "name",
-            "status",
-            "network_label",
-            "install_date",
-            "termination_date",
-            "provider",
-            "provider_segment_id",
-            "provider_segment_name",
-            "provider_segment_contract",
-            "site_a",
-            "location_a",
-            "site_b",
-            "location_b",
-            "circuits",
-            # Only basic path info, no heavy geometry
-            "path_length_km",
-            "path_source_format",
-            "path_notes",
-            "has_path_data",
-            "tags",
-        )
-        brief_fields = (
-            "id",
-            "url",
-            "display",
-            "name",
-            "status",
-            "has_path_data",
-            "tags",
-        )
-
-    def get_has_path_data(self, obj):
-        return obj.has_path_data()
-
-
-class SegmentListSerializer(NetBoxModelSerializer):
-    """Lightweight serializer for list views - excludes heavy geometry fields"""
-
-    url = serializers.HyperlinkedIdentityField(view_name="plugins-api:cesnet_service_path_plugin-api:segment-detail")
-    provider = ProviderSerializer(required=True, nested=True)
-    site_a = SiteSerializer(required=True, nested=True)
-    location_a = LocationSerializer(required=True, nested=True)
-    site_b = SiteSerializer(required=True, nested=True)
-    location_b = LocationSerializer(required=True, nested=True)
-    circuits = CircuitSerializer(required=False, many=True, nested=True)
+    # Add file upload field
+    path_file = serializers.FileField(
+        required=False,
+        write_only=True,  # Only for input, not included in output
+        help_text="Upload a file containing the path geometry. Supported formats: GeoJSON (.geojson, .json), KML (.kml), KMZ (.kmz)",
+    )
 
     # Only include lightweight path info
     has_path_data = serializers.SerializerMethodField(read_only=True)
@@ -105,6 +60,7 @@ class Meta:
             "path_source_format",
             "path_notes",
             "has_path_data",
+            "path_file",  # Add the file field
             "tags",
         )
         brief_fields = (
@@ -120,6 +76,64 @@ class Meta:
     def get_has_path_data(self, obj):
         return obj.has_path_data()
 
+    def update(self, instance, validated_data):
+        """Handle file upload during update"""
+        path_file = validated_data.pop("path_file", None)
+
+        # Update other fields first
+        instance = super().update(instance, validated_data)
+
+        # Process uploaded file if provided
+        if path_file:
+            try:
+                # Process the uploaded file using existing utility functions
+                file_format = determine_file_format_from_extension(path_file.name)
+                path_geometry = process_path_data(path_file, file_format)
+
+                # Update instance with processed geometry
+                instance.path_geometry = path_geometry
+                instance.path_source_format = file_format
+                # path_length_km will be auto-calculated in the model's save method
+                instance.save()
+
+            except DjangoValidationError as e:
+                raise serializers.ValidationError(f"Path file error: {str(e)}")
+            except Exception as e:
+                raise serializers.ValidationError(f"Error processing file '{path_file.name}': {str(e)}")
+
+        return instance
+
+    def create(self, validated_data):
+        """Handle file upload during creation"""
+        path_file = validated_data.pop("path_file", None)
+
+        # Create instance without path data first
+        instance = super().create(validated_data)
+
+        # Process uploaded file if provided
+        if path_file:
+            try:
+                # Process the uploaded file using existing utility functions
+                file_format = determine_file_format_from_extension(path_file.name)
+                path_geometry = process_path_data(path_file, file_format)
+
+                # Update instance with processed geometry
+                instance.path_geometry = path_geometry
+                instance.path_source_format = file_format
+                # path_length_km will be auto-calculated in the model's save method
+                instance.save()
+
+            except DjangoValidationError as e:
+                # Clean up created instance if path processing fails
+                instance.delete()
+                raise serializers.ValidationError(f"Path file error: {str(e)}")
+            except Exception as e:
+                # Clean up created instance if path processing fails
+                instance.delete()
+                raise serializers.ValidationError(f"Error processing file '{path_file.name}': {str(e)}")
+
+        return instance
+
 
 class SegmentDetailSerializer(NetBoxModelSerializer):
     """Full serializer with all geometry data for detail views"""

cesnet_service_path_plugin/api/serializers/segment_circuit_mapping.py

@@ -1,7 +1,6 @@
 from rest_framework import serializers
 from netbox.api.serializers import NetBoxModelSerializer
-from cesnet_service_path_plugin.api.serializers.segment import SegmentListSerializer
-from cesnet_service_path_plugin.api.serializers.service_path import ServicePathSerializer
+from cesnet_service_path_plugin.api.serializers.segment import SegmentSerializer
 from cesnet_service_path_plugin.models import SegmentCircuitMapping
 from circuits.api.serializers import CircuitSerializer
 
@@ -11,7 +10,7 @@ class SegmentCircuitMappingSerializer(NetBoxModelSerializer):
         view_name="plugins-api:cesnet_service_path_plugin-api:segmentcircuitmapping-detail"
     )
     circuit = CircuitSerializer(nested=True)
-    segment = SegmentListSerializer(nested=True)
+    segment = SegmentSerializer(nested=True)
 
     class Meta:
         model = SegmentCircuitMapping

cesnet_service_path_plugin/api/serializers/service_path.py

@@ -2,15 +2,15 @@
 from netbox.api.serializers import NetBoxModelSerializer
 from rest_framework import serializers
 
-from cesnet_service_path_plugin.api.serializers.segment import SegmentListSerializer
+from cesnet_service_path_plugin.api.serializers.segment import SegmentSerializer
 from cesnet_service_path_plugin.models import ServicePath
 
 
 class ServicePathSerializer(NetBoxModelSerializer):
     url = serializers.HyperlinkedIdentityField(
         view_name="plugins-api:cesnet_service_path_plugin-api:servicepath-detail"
     )
-    segments = SegmentListSerializer(many=True, read_only=True, nested=True)
+    segments = SegmentSerializer(many=True, read_only=True, nested=True)
     circuits = CircuitSerializer(required=False, many=True, nested=True)
 
     class Meta:

cesnet_service_path_plugin/api/serializers/service_path_segment_mapping.py

@@ -1,6 +1,6 @@
 from rest_framework import serializers
 from netbox.api.serializers import NetBoxModelSerializer
-from cesnet_service_path_plugin.api.serializers.segment import SegmentListSerializer
+from cesnet_service_path_plugin.api.serializers.segment import SegmentSerializer
 from cesnet_service_path_plugin.api.serializers.service_path import (
     ServicePathSerializer,
 )
@@ -16,7 +16,7 @@ class ServicePathSegmentMappingSerializer(NetBoxModelSerializer):
     #    required=True
     # )
     service_path = ServicePathSerializer(nested=True)
-    segment = SegmentListSerializer(nested=True)
+    segment = SegmentSerializer(nested=True)
 
     class Meta:
         model = ServicePathSegmentMapping

cesnet_service_path_plugin/api/views/segment.py

@@ -20,4 +20,5 @@ def get_serializer_class(self):
             if pathdata:
                 return SegmentDetailSerializer
 
+        # Use the updated SegmentSerializer for all other actions (including create/update)
         return SegmentSerializer

docs/API_path.md

@@ -0,0 +1,100 @@
+# API Usage Examples
+
+## Creating a New Segment with Path Data (POST)
+
+Create a new segment with all required fields and upload path geometry from a file:
+
+```bash
+curl -X POST "http://localhost:8000/api/plugins/cesnet_service_path_plugin/segments/" \
+  -H "Authorization: Token YOUR_API_TOKEN" \
+  -F "name=Test Segment API" \
+  -F "status=active" \
+  -F "provider=32" \
+  -F "site_a=314" \
+  -F "location_a=387" \
+  -F "site_b=36" \
+  -F "location_b=24" \
+  -F "network_label=API-TEST-01" \
+  -F "provider_segment_id=API-TEST-SEGMENT-001" \
+  -F "provider_segment_name=Test Provider Segment" \
+  -F "provider_segment_contract=CONTRACT-2024-001" \
+  -F "path_file=@/path/to/your/segment_path.kmz" \
+  -F "path_notes=Path data uploaded via API" \
+  -F "install_date=2024-01-15" \
+  -F "termination_date=2024-12-31"
+```
+
+**Supported file formats:**
+- GeoJSON files: `.geojson`, `.json`
+- KML files: `.kml`
+- KMZ files: `.kmz`
+
+## Updating an Existing Segment (PATCH)
+
+Update segment with ID 10 - you can update any combination of fields:
+
+### Update Path Data Only
+```bash
+curl -X PATCH "http://localhost:8000/api/plugins/cesnet_service_path_plugin/segments/10/" \
+  -H "Authorization: Token YOUR_API_TOKEN" \
+  -F "path_file=@/home/albert/cesnet/netbox/data/prubehy/segment_10_Mapa-Trasa.kmz" \
+  -F "path_notes=Updated path data via API"
+```
+
+### Update Multiple Fields Including Path Data
+```bash
+curl -X PATCH "http://localhost:8000/api/plugins/cesnet_service_path_plugin/segments/10/" \
+  -H "Authorization: Token YOUR_API_TOKEN" \
+  -F "network_label=UPDATED-LABEL" \
+  -F "provider_segment_name=Updated Provider Name" \
+  -F "status=planned" \
+  -F "path_file=@/path/to/updated_path.geojson" \
+  -F "path_notes=Updated both metadata and path geometry" \
+  -F "termination_date=2025-06-30"
+```
+
+## Important Notes
+
+1. **Authentication**: Replace `YOUR_API_TOKEN` with your actual NetBox API token
+2. **Content-Type**: Use `multipart/form-data` (automatic with `-F` flag) when uploading files
+3. **File Path**: Use absolute paths for the `path_file` parameter
+4. **Required Fields**: For POST requests, ensure all required fields are included:
+   - `name`, `status`, `provider`, `site_a`, `location_a`, `site_b`, `location_b`
+5. **Field IDs**: Use numeric IDs for foreign key fields (provider, sites, locations)
+6. **Path Processing**: Files are automatically processed and geometry is calculated
+7. **Error Handling**: Invalid files will return detailed error messages
+
+## Response Example
+
+Successful upload will return the segment data with path information:
+
+```json
+{
+  "id": 10,
+  "name": "Test Segment API",
+  "status": "active",
+  "path_length_km": "125.456",
+  "path_source_format": "kmz",
+  "path_notes": "Path data uploaded via API",
+  "has_path_data": true,
+  ...
+}
+```
+
+## Getting Field IDs
+
+To find the correct IDs for providers, sites, and locations:
+
+```bash
+# List providers
+curl -H "Authorization: Token YOUR_API_TOKEN" \
+  "http://localhost:8000/api/circuits/providers/"
+
+# List sites
+curl -H "Authorization: Token YOUR_API_TOKEN" \
+  "http://localhost:8000/api/dcim/sites/"
+
+# List locations for a specific site
+curl -H "Authorization: Token YOUR_API_TOKEN" \
+  "http://localhost:8000/api/dcim/locations/?site_id=314"
+```