Skip to content

Commit f6ef5fa

Browse files
dheeru0198pablohashescobarNarayanBavisetti
authored and
lifeiscontent
committed
[WEB-4045] feat: restructuring of the external APIs for better maintainability (#7477)
* Basic setup for drf-spectacular * Updated to only handle /api/v1 endpoints * feat: add asset and user endpoints with URL routing - Introduced new asset-related endpoints for user assets and server assets, allowing for asset uploads and management. - Added user endpoint to retrieve current user information. - Updated URL routing to include new asset and user patterns. - Enhanced issue handling with a new search endpoint for issues across multiple fields. - Expanded member management with a new endpoint for workspace members. * Group endpoints by tags * Detailed schema definitions and examples for asset endpoints * Removed unnecessary extension * Specify avatar_url field separately * chore: add project docs * chore: correct all errors * chore: added open spec in work items * feat: enhance cycle API endpoints with detailed OpenAPI specifications - Updated CycleAPIEndpoint and CycleIssueAPIEndpoint to include detailed OpenAPI schema definitions for GET, POST, PATCH, and DELETE operations. - Specified allowed HTTP methods for each endpoint in the URL routing. - Improved documentation for cycle creation, updating, and deletion, including request and response examples. * chore: added open spec in labels * chore: work item properties * feat: enhance API endpoints with OpenAPI specifications and HTTP method definitions - Added detailed OpenAPI schema definitions for various API endpoints including Intake, Module, and State. - Specified allowed HTTP methods for each endpoint in the URL routing for better clarity and documentation. - Improved request and response examples for better understanding of API usage. - Introduced unarchive functionality for cycles and modules with appropriate endpoint definitions. * chore: run formatter * Removed unnecessary settings for authentication * Refactors OpenAPI documentation structure Improves the organization and maintainability of the OpenAPI documentation by modularizing the `openapi_spec_helpers.py` file. The changes include: - Migrates common parameters, responses, examples, and authentication extensions to separate modules. - Introduces helper decorators for different endpoint types. - Updates view imports to use the new module paths. - Removes the legacy `openapi_spec_helpers.py` file. This refactoring results in a more structured and easier-to-maintain OpenAPI documentation setup. * Refactor OpenAPI endpoint specifications - Removed unnecessary parameters from the OpenAPI documentation for various endpoints in the asset, cycle, and project views. - Updated request structures to improve clarity and consistency across the API documentation. - Enhanced response formatting for better readability and maintainability. * Enhance API documentation with detailed endpoint descriptions Updated various API endpoints across the application to include comprehensive docstrings that clarify their functionality. Each endpoint now features a summary and detailed description, improving the overall understanding of their purpose and usage. This change enhances the OpenAPI specifications for better developer experience and documentation clarity. * Enhance API serializers and views with new request structures - Added new serializers for handling cycle and module issue requests, including `CycleIssueRequestSerializer`, `TransferCycleIssueRequestSerializer`, `ModuleIssueRequestSerializer`, and intake issue creation/updating serializers. - Updated existing serializers to improve clarity and maintainability, including the `UserAssetUploadSerializer` and `IssueAttachmentUploadSerializer`. - Refactored API views to utilize the new serializers, enhancing the request handling for cycle and intake issue endpoints. - Improved OpenAPI documentation by replacing inline request definitions with serializer references for better consistency and readability. * Refactor OpenAPI documentation and endpoint specifications - Replaced inline schema definitions with dedicated decorators for various endpoint types, enhancing clarity and maintainability. - Updated API views to utilize new decorators for user, cycle, intake, module, and project endpoints, improving consistency in OpenAPI documentation. - Removed unnecessary parameters and responses from endpoint specifications, streamlining the documentation for better readability. - Enhanced the organization of OpenAPI documentation by modularizing endpoint-specific decorators and parameters. * chore: correct formatting * chore: correct formatting for all api folder files * refactor: clean up serializer imports and test setup - Removed unused `StateLiteSerializer` import from the serializer module. - Updated test setup to include a noqa comment for the `django_db_setup` fixture, ensuring clarity in the code. - Added missing commas in user data dictionary for consistency. * feat: add project creation and update serializers with validation - Introduced `ProjectCreateSerializer` and `ProjectUpdateSerializer` to handle project creation and updates, respectively. - Implemented validation to ensure project leads and default assignees are members of the workspace. - Updated API views to utilize the new serializers for creating and updating projects, enhancing request handling. - Added OpenAPI documentation references for the new serializers in the project API endpoints. * feat: update serializers to include additional read-only fields * refactor: rename intake issue serializers and enhance structure - Renamed `CreateIntakeIssueRequestSerializer` to `IntakeIssueCreateSerializer` and `UpdateIntakeIssueRequestSerializer` to `IntakeIssueUpdateSerializer` for clarity. - Introduced `IssueSerializer` for nested issue data in intake requests, improving the organization of serializer logic. - Updated API views to utilize the new serializer names, ensuring consistency across the codebase. * refactor: rename issue serializer for intake and enhance API documentation - Renamed `IssueSerializer` to `IssueForIntakeSerializer` for better clarity in the context of intake issues. - Updated references in `IntakeIssueCreateSerializer` and `IntakeIssueUpdateSerializer` to use the new `IssueForIntakeSerializer`. - Added OpenAPI documentation for the `get_workspace_work_item` endpoint, detailing parameters and responses for improved clarity. * chore: modules and cycles serializers * feat: add new serializers for label and issue link management - Introduced `LabelCreateUpdateSerializer`, `IssueLinkCreateSerializer`, `IssueLinkUpdateSerializer`, and `IssueCommentCreateSerializer` to enhance the handling of label and issue link data. - Updated existing API views to utilize the new serializers for creating and updating labels, issue links, and comments, improving request handling and validation. - Added `IssueSearchSerializer` for searching issues, streamlining the search functionality in the API. * Don't consider read only fields as required * Add setting to separate request and response definitions * Fixed avatar_url warning on openapi spec generation * Made spectacular disabled by default * Moved spectacular settings into separate file and added detailed descriptions to tags * Specify methods for asset urls * Better server names * Enhance API documentation with summaries for various endpoints - Added summary descriptions for user asset, cycle, intake, issue, member, module, project, state, and user API endpoints to improve clarity and usability of the API documentation. - Updated the OpenAPI specifications to reflect these changes, ensuring better understanding for developers interacting with the API. * Add contact information to OpenAPI settings - Included contact details for Plane in the OpenAPI settings to enhance API documentation and provide developers with a direct point of contact for support. - This addition aims to improve the overall usability and accessibility of the API documentation. * Reordered tags and improved description relavancy * Enhance OpenAPI documentation for cycle and issue endpoints - Added response definitions for the `get_cycle_issues` and `delete_cycle_issue` methods in the CycleIssueAPIEndpoint to clarify expected outcomes. - Included additional response codes for the IssueSearchEndpoint to handle various error scenarios, improving the overall API documentation and usability. * Enhance serializer documentation across multiple files - Updated docstrings for various serializers including UserAssetUploadSerializer, AssetUpdateSerializer, and others to provide clearer descriptions of their functionality and usage. - Improved consistency in formatting and language across serializer classes to enhance readability and maintainability. - Added detailed explanations for new serializers related to project, module, and cycle management, ensuring comprehensive documentation for developers. * Refactor API endpoints for cycles, intake, modules, projects, and states - Replaced existing API endpoint classes with more descriptive names such as CycleListCreateAPIEndpoint, CycleDetailAPIEndpoint, IntakeIssueListCreateAPIEndpoint, and others to enhance clarity. - Updated URL patterns to reflect the new endpoint names, ensuring consistency across the API. - Improved documentation and method summaries for better understanding of endpoint functionalities. - Enhanced query handling in the new endpoint classes to streamline data retrieval and improve performance. * Refactor issue and label API endpoints for clarity and functionality - Renamed existing API endpoint classes to more descriptive names such as IssueListCreateAPIEndpoint, IssueDetailAPIEndpoint, LabelListCreateAPIEndpoint, and LabelDetailAPIEndpoint to enhance clarity. - Updated URL patterns to reflect the new endpoint names, ensuring consistency across the API. - Improved method summaries and documentation for better understanding of endpoint functionalities. - Streamlined query handling in the new endpoint classes to enhance data retrieval and performance. * Refactor asset API endpoint methods and introduce new status enums - Updated the GenericAssetEndpoint to only allow POST requests for asset creation, removing the GET method. - Modified the get method to require asset_id, ensuring that asset retrieval is always tied to a specific asset. - Added new IntakeIssueStatus and ModuleStatus enums to improve clarity and management of asset and module states. - Enhanced OpenAPI settings to include these new enums for better documentation and usability. * enforce naming convention * Added LICENSE to openapi spec * Enhance OpenAPI documentation for various API endpoints - Updated API endpoints in asset, cycle, intake, issue, module, project, and state views to include OpenApiRequest and OpenApiExample for better request documentation. - Added example requests for creating and updating resources, improving clarity for API consumers. - Ensured consistent use of OpenApi utilities across all relevant endpoints to enhance overall API documentation quality. * Enhance OpenAPI documentation for various API endpoints - Added detailed descriptions to multiple API endpoints across asset, cycle, intake, issue, module, project, state, and user views to improve clarity for API consumers. - Ensured consistent documentation practices by including descriptions that outline the purpose and functionality of each endpoint. - This update aims to enhance the overall usability and understanding of the API documentation. * Update OpenAPI examples and enhance project queryset logic - Changed example fields in OpenAPI documentation for issue comments from "content" to "comment_html" to reflect the correct structure. - Introduced a new `get_queryset` method in the ProjectDetailAPIEndpoint to filter projects based on user membership and workspace, while also annotating additional project-related data such as total members, cycles, and modules. - Updated permission checks to use the correct attribute name for project identifiers, ensuring accurate permission handling. * Enhance OpenAPI documentation and add response examples - Updated multiple API endpoints across asset, cycle, intake, issue, module, project, state, and user views to include new OpenApiResponse examples for better clarity on expected outcomes. - Introduced new parameters for project and issue identifiers to improve request handling and documentation consistency. - Enhanced existing responses with detailed examples to aid API consumers in understanding the expected data structure and error handling. - This update aims to improve the overall usability and clarity of the API documentation. * refactor: update terminology from 'issues' to 'work items' across multiple API endpoints for consistency and clarity * use common timezones from pytz for choices * Moved the openapi utils to the new folder structure * Added exception logging in GenericAssetEndpoint to improve error handling * Fixed code rabbit suggestions * Refactored IssueDetailAPIEndpoint to streamline issue retrieval and response handling, removing redundant external ID checks and custom ordering logic. --------- Co-authored-by: pablohashescobar <nikhilschacko@gmail.com> Co-authored-by: NarayanBavisetti <narayan3119@gmail.com>
1 parent 3195096 commit f6ef5fa

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

64 files changed

+7657
-525
lines changed

‎apps/api/plane/api/apps.py‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,10 @@
33

44
class ApiConfig(AppConfig):
55
name = "plane.api"
6+
7+
def ready(self):
8+
# Import authentication extensions to register them with drf-spectacular
9+
try:
10+
import plane.utils.openapi.auth # noqa
11+
except ImportError:
12+
pass

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

Lines changed: 41 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,55 @@
11
from .user import UserLiteSerializer
22
from .workspace import WorkspaceLiteSerializer
3-
from .project import ProjectSerializer, ProjectLiteSerializer
3+
from .project import (
4+
ProjectSerializer,
5+
ProjectLiteSerializer,
6+
ProjectCreateSerializer,
7+
ProjectUpdateSerializer,
8+
)
49
from .issue import (
510
IssueSerializer,
11+
LabelCreateUpdateSerializer,
612
LabelSerializer,
713
IssueLinkSerializer,
814
IssueCommentSerializer,
915
IssueAttachmentSerializer,
1016
IssueActivitySerializer,
1117
IssueExpandSerializer,
1218
IssueLiteSerializer,
19+
IssueAttachmentUploadSerializer,
20+
IssueSearchSerializer,
21+
IssueCommentCreateSerializer,
22+
IssueLinkCreateSerializer,
23+
IssueLinkUpdateSerializer,
1324
)
1425
from .state import StateLiteSerializer, StateSerializer
15-
from .cycle import CycleSerializer, CycleIssueSerializer, CycleLiteSerializer
16-
from .module import ModuleSerializer, ModuleIssueSerializer, ModuleLiteSerializer
17-
from .intake import IntakeIssueSerializer
26+
from .cycle import (
27+
CycleSerializer,
28+
CycleIssueSerializer,
29+
CycleLiteSerializer,
30+
CycleIssueRequestSerializer,
31+
TransferCycleIssueRequestSerializer,
32+
CycleCreateSerializer,
33+
CycleUpdateSerializer,
34+
)
35+
from .module import (
36+
ModuleSerializer,
37+
ModuleIssueSerializer,
38+
ModuleLiteSerializer,
39+
ModuleIssueRequestSerializer,
40+
ModuleCreateSerializer,
41+
ModuleUpdateSerializer,
42+
)
43+
from .intake import (
44+
IntakeIssueSerializer,
45+
IntakeIssueCreateSerializer,
46+
IntakeIssueUpdateSerializer,
47+
)
1848
from .estimate import EstimatePointSerializer
49+
from .asset import (
50+
UserAssetUploadSerializer,
51+
AssetUpdateSerializer,
52+
GenericAssetUploadSerializer,
53+
GenericAssetUpdateSerializer,
54+
FileAssetSerializer,
55+
)

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

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# Third party imports
2+
from rest_framework import serializers
3+
4+
# Module imports
5+
from .base import BaseSerializer
6+
from plane.db.models import FileAsset
7+
8+
9+
class UserAssetUploadSerializer(serializers.Serializer):
10+
"""
11+
Serializer for user asset upload requests.
12+
13+
This serializer validates the metadata required to generate a presigned URL
14+
for uploading user profile assets (avatar or cover image) directly to S3 storage.
15+
Supports JPEG, PNG, WebP, JPG, and GIF image formats with size validation.
16+
"""
17+
18+
name = serializers.CharField(help_text="Original filename of the asset")
19+
type = serializers.ChoiceField(
20+
choices=[
21+
("image/jpeg", "JPEG"),
22+
("image/png", "PNG"),
23+
("image/webp", "WebP"),
24+
("image/jpg", "JPG"),
25+
("image/gif", "GIF"),
26+
],
27+
default="image/jpeg",
28+
help_text="MIME type of the file",
29+
style={"placeholder": "image/jpeg"},
30+
)
31+
size = serializers.IntegerField(help_text="File size in bytes")
32+
entity_type = serializers.ChoiceField(
33+
choices=[
34+
(FileAsset.EntityTypeContext.USER_AVATAR, "User Avatar"),
35+
(FileAsset.EntityTypeContext.USER_COVER, "User Cover"),
36+
],
37+
help_text="Type of user asset",
38+
)
39+
40+
41+
class AssetUpdateSerializer(serializers.Serializer):
42+
"""
43+
Serializer for asset status updates after successful upload completion.
44+
45+
Handles post-upload asset metadata updates including attribute modifications
46+
and upload confirmation for S3-based file storage workflows.
47+
"""
48+
49+
attributes = serializers.JSONField(
50+
required=False, help_text="Additional attributes to update for the asset"
51+
)
52+
53+
54+
class GenericAssetUploadSerializer(serializers.Serializer):
55+
"""
56+
Serializer for generic asset upload requests with project association.
57+
58+
Validates metadata for generating presigned URLs for workspace assets including
59+
project association, external system tracking, and file validation for
60+
document management and content storage workflows.
61+
"""
62+
63+
name = serializers.CharField(help_text="Original filename of the asset")
64+
type = serializers.CharField(required=False, help_text="MIME type of the file")
65+
size = serializers.IntegerField(help_text="File size in bytes")
66+
project_id = serializers.UUIDField(
67+
required=False,
68+
help_text="UUID of the project to associate with the asset",
69+
style={"placeholder": "123e4567-e89b-12d3-a456-426614174000"},
70+
)
71+
external_id = serializers.CharField(
72+
required=False,
73+
help_text="External identifier for the asset (for integration tracking)",
74+
)
75+
external_source = serializers.CharField(
76+
required=False, help_text="External source system (for integration tracking)"
77+
)
78+
79+
80+
class GenericAssetUpdateSerializer(serializers.Serializer):
81+
"""
82+
Serializer for generic asset upload confirmation and status management.
83+
84+
Handles post-upload status updates for workspace assets including
85+
upload completion marking and metadata finalization.
86+
"""
87+
88+
is_uploaded = serializers.BooleanField(
89+
default=True, help_text="Whether the asset has been successfully uploaded"
90+
)
91+
92+
93+
class FileAssetSerializer(BaseSerializer):
94+
"""
95+
Comprehensive file asset serializer with complete metadata and URL generation.
96+
97+
Provides full file asset information including storage metadata, access URLs,
98+
relationship data, and upload status for complete asset management workflows.
99+
"""
100+
101+
asset_url = serializers.CharField(read_only=True)
102+
103+
class Meta:
104+
model = FileAsset
105+
fields = "__all__"
106+
read_only_fields = [
107+
"id",
108+
"created_by",
109+
"updated_by",
110+
"created_at",
111+
"updated_at",
112+
"workspace",
113+
"project",
114+
"issue",
115+
"comment",
116+
"page",
117+
"draft_issue",
118+
"user",
119+
"is_deleted",
120+
"deleted_at",
121+
"storage_metadata",
122+
"asset_url",
123+
]

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

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,13 @@
33

44

55
class BaseSerializer(serializers.ModelSerializer):
6+
"""
7+
Base serializer providing common functionality for all model serializers.
8+
9+
Features field filtering, dynamic expansion of related fields, and standardized
10+
primary key handling for consistent API responses across the application.
11+
"""
12+
613
id = serializers.PrimaryKeyRelatedField(read_only=True)
714

815
def __init__(self, *args, **kwargs):

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

Lines changed: 104 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -8,16 +8,13 @@
88
from plane.utils.timezone_converter import convert_to_utc
99

1010

11-
class CycleSerializer(BaseSerializer):
12-
total_issues = serializers.IntegerField(read_only=True)
13-
cancelled_issues = serializers.IntegerField(read_only=True)
14-
completed_issues = serializers.IntegerField(read_only=True)
15-
started_issues = serializers.IntegerField(read_only=True)
16-
unstarted_issues = serializers.IntegerField(read_only=True)
17-
backlog_issues = serializers.IntegerField(read_only=True)
18-
total_estimates = serializers.FloatField(read_only=True)
19-
completed_estimates = serializers.FloatField(read_only=True)
20-
started_estimates = serializers.FloatField(read_only=True)
11+
class CycleCreateSerializer(BaseSerializer):
12+
"""
13+
Serializer for creating cycles with timezone handling and date validation.
14+
15+
Manages cycle creation including project timezone conversion, date range validation,
16+
and UTC normalization for time-bound iteration planning and sprint management.
17+
"""
2118

2219
def __init__(self, *args, **kwargs):
2320
super().__init__(*args, **kwargs)
@@ -27,6 +24,29 @@ def __init__(self, *args, **kwargs):
2724
self.fields["start_date"].timezone = project_timezone
2825
self.fields["end_date"].timezone = project_timezone
2926

27+
class Meta:
28+
model = Cycle
29+
fields = [
30+
"name",
31+
"description",
32+
"start_date",
33+
"end_date",
34+
"owned_by",
35+
"external_source",
36+
"external_id",
37+
"timezone",
38+
]
39+
read_only_fields = [
40+
"id",
41+
"workspace",
42+
"project",
43+
"created_by",
44+
"updated_by",
45+
"created_at",
46+
"updated_at",
47+
"deleted_at",
48+
]
49+
3050
def validate(self, data):
3151
if (
3252
data.get("start_date", None) is not None
@@ -59,6 +79,40 @@ def validate(self, data):
5979
)
6080
return data
6181

82+
83+
class CycleUpdateSerializer(CycleCreateSerializer):
84+
"""
85+
Serializer for updating cycles with enhanced ownership management.
86+
87+
Extends cycle creation with update-specific features including ownership
88+
assignment and modification tracking for cycle lifecycle management.
89+
"""
90+
91+
class Meta(CycleCreateSerializer.Meta):
92+
model = Cycle
93+
fields = CycleCreateSerializer.Meta.fields + [
94+
"owned_by",
95+
]
96+
97+
98+
class CycleSerializer(BaseSerializer):
99+
"""
100+
Cycle serializer with comprehensive project metrics and time tracking.
101+
102+
Provides cycle details including work item counts by status, progress estimates,
103+
and time-bound iteration data for project management and sprint planning.
104+
"""
105+
106+
total_issues = serializers.IntegerField(read_only=True)
107+
cancelled_issues = serializers.IntegerField(read_only=True)
108+
completed_issues = serializers.IntegerField(read_only=True)
109+
started_issues = serializers.IntegerField(read_only=True)
110+
unstarted_issues = serializers.IntegerField(read_only=True)
111+
backlog_issues = serializers.IntegerField(read_only=True)
112+
total_estimates = serializers.FloatField(read_only=True)
113+
completed_estimates = serializers.FloatField(read_only=True)
114+
started_estimates = serializers.FloatField(read_only=True)
115+
62116
class Meta:
63117
model = Cycle
64118
fields = "__all__"
@@ -76,6 +130,13 @@ class Meta:
76130

77131

78132
class CycleIssueSerializer(BaseSerializer):
133+
"""
134+
Serializer for cycle-issue relationships with sub-issue counting.
135+
136+
Manages the association between cycles and work items, including
137+
hierarchical issue tracking for nested work item structures.
138+
"""
139+
79140
sub_issues_count = serializers.IntegerField(read_only=True)
80141

81142
class Meta:
@@ -85,6 +146,39 @@ class Meta:
85146

86147

87148
class CycleLiteSerializer(BaseSerializer):
149+
"""
150+
Lightweight cycle serializer for minimal data transfer.
151+
152+
Provides essential cycle information without computed metrics,
153+
optimized for list views and reference lookups.
154+
"""
155+
88156
class Meta:
89157
model = Cycle
90158
fields = "__all__"
159+
160+
161+
class CycleIssueRequestSerializer(serializers.Serializer):
162+
"""
163+
Serializer for bulk work item assignment to cycles.
164+
165+
Validates work item ID lists for batch operations including
166+
cycle assignment and sprint planning workflows.
167+
"""
168+
169+
issues = serializers.ListField(
170+
child=serializers.UUIDField(), help_text="List of issue IDs to add to the cycle"
171+
)
172+
173+
174+
class TransferCycleIssueRequestSerializer(serializers.Serializer):
175+
"""
176+
Serializer for transferring work items between cycles.
177+
178+
Handles work item migration between cycles including validation
179+
and relationship updates for sprint reallocation workflows.
180+
"""
181+
182+
new_cycle_id = serializers.UUIDField(
183+
help_text="ID of the target cycle to transfer issues to"
184+
)

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

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,13 @@
44

55

66
class EstimatePointSerializer(BaseSerializer):
7+
"""
8+
Serializer for project estimation points and story point values.
9+
10+
Handles numeric estimation data for work item sizing and sprint planning,
11+
providing standardized point values for project velocity calculations.
12+
"""
13+
714
class Meta:
815
model = EstimatePoint
916
fields = ["id", "value"]

0 commit comments

Comments
 (0)