From 18766c6f278a875e901a30149598ad8cec5a9642 Mon Sep 17 00:00:00 2001 From: Muhammad Faraz Maqsood Date: Mon, 9 Mar 2026 13:50:11 +0500 Subject: [PATCH 1/3] docs: add ADR for standardizing serializer usage --- .../0025-standardize-serializer-usage.rst | 114 ++++++++++++++++++ 1 file changed, 114 insertions(+) create mode 100644 docs/decisions/0025-standardize-serializer-usage.rst diff --git a/docs/decisions/0025-standardize-serializer-usage.rst b/docs/decisions/0025-standardize-serializer-usage.rst new file mode 100644 index 000000000000..61f0c54a3be7 --- /dev/null +++ b/docs/decisions/0025-standardize-serializer-usage.rst @@ -0,0 +1,114 @@ +Standardize Serializer Usage Across APIs +======================================== + +:Status: Proposed +:Date: 2026-03-09 +:Deciders: API Working Group +:Technical Story: Open edX REST API Standards - Serializer standardization for consistency + +Context +------- + +Many Open edX platform API endpoints manually construct JSON responses using Python dictionaries instead of Django REST Framework (DRF) serializers. This leads to inconsistent schema responses, makes validation errors harder to manage, and creates unpredictable formats that AI and third-party systems struggle with. + +The recommendation in the standards document is to enforce serializer-based input/output handling for all endpoints to ensure consistent response contracts and improve validation. + +Decision +-------- + +We will standardize all Open edX REST APIs to use **DRF serializers** for request and response handling. + +Implementation requirements: + +* All API views MUST define explicit serializers for request and response handling. +* Replace manual JSON construction with serializer-based responses. +* Use serializers for both input validation and output formatting. +* Ensure serializers are properly documented with field descriptions and validation rules. +* Maintain backward compatibility where possible during migration. + +Relevance in edx-platform +------------------------- + +Current patterns that should be migrated: + +* **Certificates API** (``/api/certificates/v0/``) constructs JSON manually with nested dictionaries. +* **Enrollment API** endpoints manually build response objects without serializers. +* **Course API** views use hand-coded JSON responses instead of structured serializers. + +Code example (target serializer usage) +-------------------------------------- + +**Example serializer and APIView using DRF best practices:** + +.. code-block:: python + + # serializers.py + from rest_framework import serializers + + class CertificateSerializer(serializers.Serializer): + username = serializers.CharField( + help_text="The username of the certificate holder" + ) + course_id = serializers.CharField( + help_text="The course identifier" + ) + status = serializers.CharField( + help_text="The certificate status (e.g., downloadable, generating)" + ) + grade = serializers.FloatField( + help_text="The final grade achieved" + ) + + # views.py + from rest_framework.views import APIView + from rest_framework.response import Response + from rest_framework import status + + class CertificateAPIView(APIView): + def get(self, request): + data = { + "username": "john_doe", + "course_id": "course-v1:edX+DemoX+1T2024", + "status": "downloadable", + "grade": 0.95, + } + serializer = CertificateSerializer(data) + return Response(serializer.data, status=status.HTTP_200_OK) + +Consequences +------------ + +Positive +~~~~~~~~ + +* Simplifies validation and ensures consistent response contracts. +* Improves AI compatibility through predictable data structures. +* Enables automatic schema generation and documentation. +* Reduces code duplication and maintenance overhead. + +Negative / Trade-offs +~~~~~~~~~~~~~~~~~~~~~ + +* Requires refactoring existing endpoints that manually construct JSON. +* Initial development overhead for creating comprehensive serializers. +* May require updates to existing client code that expects legacy formats. + +Alternatives Considered +----------------------- + +* **Keep manual JSON construction**: rejected due to inconsistency and maintenance burden. +* **Use DRF defaults only**: rejected because explicit serializers provide better validation and documentation. + +Rollout Plan +------------ + +1. Audit existing endpoints to identify those using manual JSON construction. +2. Create a library of common serializers for shared data structures. +3. Migrate high-impact endpoints first (certificates, enrollment, courses). +4. Update tests to validate serializer-based responses. +5. Update API documentation to reflect new serializer-based contracts. + +References +---------- + +* Open edX REST API Standards: "Serializer Usage" recommendations for API consistency. From 69f01b2807bef742ff7c716022fe46f6658f3cb0 Mon Sep 17 00:00:00 2001 From: Muhammad Faraz Maqsood Date: Wed, 11 Mar 2026 19:35:53 +0500 Subject: [PATCH 2/3] docs: fix typo --- docs/decisions/0025-standardize-serializer-usage.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/decisions/0025-standardize-serializer-usage.rst b/docs/decisions/0025-standardize-serializer-usage.rst index 61f0c54a3be7..dad6433bc457 100644 --- a/docs/decisions/0025-standardize-serializer-usage.rst +++ b/docs/decisions/0025-standardize-serializer-usage.rst @@ -24,7 +24,7 @@ Implementation requirements: * Replace manual JSON construction with serializer-based responses. * Use serializers for both input validation and output formatting. * Ensure serializers are properly documented with field descriptions and validation rules. -* Maintain backward compatibility where possible during migration. +* Maintain backward compatibility for all APIs during migration. Relevance in edx-platform ------------------------- From e89e3e5be12a9e81418fe0c0604efe115b23e7b0 Mon Sep 17 00:00:00 2001 From: Muhammad Faraz Maqsood Date: Thu, 12 Mar 2026 14:09:02 +0500 Subject: [PATCH 3/3] docs: remove confusing statement --- docs/decisions/0025-standardize-serializer-usage.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/decisions/0025-standardize-serializer-usage.rst b/docs/decisions/0025-standardize-serializer-usage.rst index dad6433bc457..0e96fd963223 100644 --- a/docs/decisions/0025-standardize-serializer-usage.rst +++ b/docs/decisions/0025-standardize-serializer-usage.rst @@ -11,8 +11,6 @@ Context Many Open edX platform API endpoints manually construct JSON responses using Python dictionaries instead of Django REST Framework (DRF) serializers. This leads to inconsistent schema responses, makes validation errors harder to manage, and creates unpredictable formats that AI and third-party systems struggle with. -The recommendation in the standards document is to enforce serializer-based input/output handling for all endpoints to ensure consistent response contracts and improve validation. - Decision --------