[WEB-4045] feat: restructuring of the external APIs for better maintainability

apps/api/plane/api/apps.py

@@ -3,3 +3,10 @@
 
 class ApiConfig(AppConfig):
     name = "plane.api"
+
+    def ready(self):
+        # Import authentication extensions to register them with drf-spectacular
+        try:
+            import plane.utils.openapi.auth  # noqa
+        except ImportError:
+            pass

apps/api/plane/api/serializers/__init__.py

@@ -1,18 +1,55 @@
 from .user import UserLiteSerializer
 from .workspace import WorkspaceLiteSerializer
-from .project import ProjectSerializer, ProjectLiteSerializer
+from .project import (
+    ProjectSerializer,
+    ProjectLiteSerializer,
+    ProjectCreateSerializer,
+    ProjectUpdateSerializer,
+)
 from .issue import (
     IssueSerializer,
+    LabelCreateUpdateSerializer,
     LabelSerializer,
     IssueLinkSerializer,
     IssueCommentSerializer,
     IssueAttachmentSerializer,
     IssueActivitySerializer,
     IssueExpandSerializer,
     IssueLiteSerializer,
+    IssueAttachmentUploadSerializer,
+    IssueSearchSerializer,
+    IssueCommentCreateSerializer,
+    IssueLinkCreateSerializer,
+    IssueLinkUpdateSerializer,
 )
 from .state import StateLiteSerializer, StateSerializer
-from .cycle import CycleSerializer, CycleIssueSerializer, CycleLiteSerializer
-from .module import ModuleSerializer, ModuleIssueSerializer, ModuleLiteSerializer
-from .intake import IntakeIssueSerializer
+from .cycle import (
+    CycleSerializer,
+    CycleIssueSerializer,
+    CycleLiteSerializer,
+    CycleIssueRequestSerializer,
+    TransferCycleIssueRequestSerializer,
+    CycleCreateSerializer,
+    CycleUpdateSerializer,
+)
+from .module import (
+    ModuleSerializer,
+    ModuleIssueSerializer,
+    ModuleLiteSerializer,
+    ModuleIssueRequestSerializer,
+    ModuleCreateSerializer,
+    ModuleUpdateSerializer,
+)
+from .intake import (
+    IntakeIssueSerializer,
+    IntakeIssueCreateSerializer,
+    IntakeIssueUpdateSerializer,
+)
 from .estimate import EstimatePointSerializer
+from .asset import (
+    UserAssetUploadSerializer,
+    AssetUpdateSerializer,
+    GenericAssetUploadSerializer,
+    GenericAssetUpdateSerializer,
+    FileAssetSerializer,
+)

apps/api/plane/api/serializers/asset.py

@@ -0,0 +1,123 @@
+# Third party imports
+from rest_framework import serializers
+
+# Module imports
+from .base import BaseSerializer
+from plane.db.models import FileAsset
+
+
+class UserAssetUploadSerializer(serializers.Serializer):
+    """
+    Serializer for user asset upload requests.
+
+    This serializer validates the metadata required to generate a presigned URL
+    for uploading user profile assets (avatar or cover image) directly to S3 storage.
+    Supports JPEG, PNG, WebP, JPG, and GIF image formats with size validation.
+    """
+
+    name = serializers.CharField(help_text="Original filename of the asset")
+    type = serializers.ChoiceField(
+        choices=[
+            ("image/jpeg", "JPEG"),
+            ("image/png", "PNG"),
+            ("image/webp", "WebP"),
+            ("image/jpg", "JPG"),
+            ("image/gif", "GIF"),
+        ],
+        default="image/jpeg",
+        help_text="MIME type of the file",
+        style={"placeholder": "image/jpeg"},
+    )
+    size = serializers.IntegerField(help_text="File size in bytes")
+    entity_type = serializers.ChoiceField(
+        choices=[
+            (FileAsset.EntityTypeContext.USER_AVATAR, "User Avatar"),
+            (FileAsset.EntityTypeContext.USER_COVER, "User Cover"),
+        ],
+        help_text="Type of user asset",
+    )
+
+
+class AssetUpdateSerializer(serializers.Serializer):
+    """
+    Serializer for asset status updates after successful upload completion.
+
+    Handles post-upload asset metadata updates including attribute modifications
+    and upload confirmation for S3-based file storage workflows.
+    """
+
+    attributes = serializers.JSONField(
+        required=False, help_text="Additional attributes to update for the asset"
+    )
+
+
+class GenericAssetUploadSerializer(serializers.Serializer):
+    """
+    Serializer for generic asset upload requests with project association.
+
+    Validates metadata for generating presigned URLs for workspace assets including
+    project association, external system tracking, and file validation for
+    document management and content storage workflows.
+    """
+
+    name = serializers.CharField(help_text="Original filename of the asset")
+    type = serializers.CharField(required=False, help_text="MIME type of the file")
+    size = serializers.IntegerField(help_text="File size in bytes")
+    project_id = serializers.UUIDField(
+        required=False,
+        help_text="UUID of the project to associate with the asset",
+        style={"placeholder": "123e4567-e89b-12d3-a456-426614174000"},
+    )
+    external_id = serializers.CharField(
+        required=False,
+        help_text="External identifier for the asset (for integration tracking)",
+    )
+    external_source = serializers.CharField(
+        required=False, help_text="External source system (for integration tracking)"
+    )
+
+
+class GenericAssetUpdateSerializer(serializers.Serializer):
+    """
+    Serializer for generic asset upload confirmation and status management.
+
+    Handles post-upload status updates for workspace assets including
+    upload completion marking and metadata finalization.
+    """
+
+    is_uploaded = serializers.BooleanField(
+        default=True, help_text="Whether the asset has been successfully uploaded"
+    )
+
+
+class FileAssetSerializer(BaseSerializer):
+    """
+    Comprehensive file asset serializer with complete metadata and URL generation.
+
+    Provides full file asset information including storage metadata, access URLs,
+    relationship data, and upload status for complete asset management workflows.
+    """
+
+    asset_url = serializers.CharField(read_only=True)
+
+    class Meta:
+        model = FileAsset
+        fields = "__all__"
+        read_only_fields = [
+            "id",
+            "created_by",
+            "updated_by",
+            "created_at",
+            "updated_at",
+            "workspace",
+            "project",
+            "issue",
+            "comment",
+            "page",
+            "draft_issue",
+            "user",
+            "is_deleted",
+            "deleted_at",
+            "storage_metadata",
+            "asset_url",
+        ]

apps/api/plane/api/serializers/base.py

@@ -3,6 +3,13 @@
 
 
 class BaseSerializer(serializers.ModelSerializer):
+    """
+    Base serializer providing common functionality for all model serializers.
+
+    Features field filtering, dynamic expansion of related fields, and standardized
+    primary key handling for consistent API responses across the application.
+    """
+
     id = serializers.PrimaryKeyRelatedField(read_only=True)
 
     def __init__(self, *args, **kwargs):

apps/api/plane/api/serializers/cycle.py

@@ -8,16 +8,13 @@
 from plane.utils.timezone_converter import convert_to_utc
 
 
-class CycleSerializer(BaseSerializer):
-    total_issues = serializers.IntegerField(read_only=True)
-    cancelled_issues = serializers.IntegerField(read_only=True)
-    completed_issues = serializers.IntegerField(read_only=True)
-    started_issues = serializers.IntegerField(read_only=True)
-    unstarted_issues = serializers.IntegerField(read_only=True)
-    backlog_issues = serializers.IntegerField(read_only=True)
-    total_estimates = serializers.FloatField(read_only=True)
-    completed_estimates = serializers.FloatField(read_only=True)
-    started_estimates = serializers.FloatField(read_only=True)
+class CycleCreateSerializer(BaseSerializer):
+    """
+    Serializer for creating cycles with timezone handling and date validation.
+
+    Manages cycle creation including project timezone conversion, date range validation,
+    and UTC normalization for time-bound iteration planning and sprint management.
+    """
 
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
@@ -27,6 +24,29 @@ def __init__(self, *args, **kwargs):
             self.fields["start_date"].timezone = project_timezone
             self.fields["end_date"].timezone = project_timezone
 
+    class Meta:
+        model = Cycle
+        fields = [
+            "name",
+            "description",
+            "start_date",
+            "end_date",
+            "owned_by",
+            "external_source",
+            "external_id",
+            "timezone",
+        ]
+        read_only_fields = [
+            "id",
+            "workspace",
+            "project",
+            "created_by",
+            "updated_by",
+            "created_at",
+            "updated_at",
+            "deleted_at",
+        ]
+
     def validate(self, data):
         if (
             data.get("start_date", None) is not None
@@ -59,6 +79,40 @@ def validate(self, data):
             )
         return data
 
+
+class CycleUpdateSerializer(CycleCreateSerializer):
+    """
+    Serializer for updating cycles with enhanced ownership management.
+
+    Extends cycle creation with update-specific features including ownership
+    assignment and modification tracking for cycle lifecycle management.
+    """
+
+    class Meta(CycleCreateSerializer.Meta):
+        model = Cycle
+        fields = CycleCreateSerializer.Meta.fields + [
+            "owned_by",
+        ]
+
+
+class CycleSerializer(BaseSerializer):
+    """
+    Cycle serializer with comprehensive project metrics and time tracking.
+
+    Provides cycle details including work item counts by status, progress estimates,
+    and time-bound iteration data for project management and sprint planning.
+    """
+
+    total_issues = serializers.IntegerField(read_only=True)
+    cancelled_issues = serializers.IntegerField(read_only=True)
+    completed_issues = serializers.IntegerField(read_only=True)
+    started_issues = serializers.IntegerField(read_only=True)
+    unstarted_issues = serializers.IntegerField(read_only=True)
+    backlog_issues = serializers.IntegerField(read_only=True)
+    total_estimates = serializers.FloatField(read_only=True)
+    completed_estimates = serializers.FloatField(read_only=True)
+    started_estimates = serializers.FloatField(read_only=True)
+
     class Meta:
         model = Cycle
         fields = "__all__"
@@ -76,6 +130,13 @@ class Meta:
 
 
 class CycleIssueSerializer(BaseSerializer):
+    """
+    Serializer for cycle-issue relationships with sub-issue counting.
+
+    Manages the association between cycles and work items, including
+    hierarchical issue tracking for nested work item structures.
+    """
+
     sub_issues_count = serializers.IntegerField(read_only=True)
 
     class Meta:
@@ -85,6 +146,39 @@ class Meta:
 
 
 class CycleLiteSerializer(BaseSerializer):
+    """
+    Lightweight cycle serializer for minimal data transfer.
+
+    Provides essential cycle information without computed metrics,
+    optimized for list views and reference lookups.
+    """
+
     class Meta:
         model = Cycle
         fields = "__all__"
+
+
+class CycleIssueRequestSerializer(serializers.Serializer):
+    """
+    Serializer for bulk work item assignment to cycles.
+
+    Validates work item ID lists for batch operations including
+    cycle assignment and sprint planning workflows.
+    """
+
+    issues = serializers.ListField(
+        child=serializers.UUIDField(), help_text="List of issue IDs to add to the cycle"
+    )
+
+
+class TransferCycleIssueRequestSerializer(serializers.Serializer):
+    """
+    Serializer for transferring work items between cycles.
+
+    Handles work item migration between cycles including validation
+    and relationship updates for sprint reallocation workflows.
+    """
+
+    new_cycle_id = serializers.UUIDField(
+        help_text="ID of the target cycle to transfer issues to"
+    )

apps/api/plane/api/serializers/estimate.py

@@ -4,6 +4,13 @@
 
 
 class EstimatePointSerializer(BaseSerializer):
+    """
+    Serializer for project estimation points and story point values.
+
+    Handles numeric estimation data for work item sizing and sprint planning,
+    providing standardized point values for project velocity calculations.
+    """
+
     class Meta:
         model = EstimatePoint
         fields = ["id", "value"]