docs: ADRs for axim api improvements

docs/decisions/0025-standardize-serializer-usage.rst

@@ -0,0 +1,113 @@
+Standardize Serializer Usage Across APIs
+========================================
+
+:Status: Accepted
+: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.
+
+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 for all APIs during migration. While the goal is fully compatible DRF serializers, if that is not possible and we must make a backwards incompatible change, that change MUST be handled by creating a new version of the API and transitioning to that API using the deprecation process.
+
+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.
+* Rare backward incompatibilities 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.
+* **Use newer ways of managing API responses such as dataclasses or pydantic**: rejected due to complexity and unknowns in transitioning from two existing patterns (manual JSON and DRF serializers) to a third approach. While these python libraries offer better ergonomics, migration would require checking nested serializers, complex validation, and ModelSerializer-heavy endpoints. To move to some new format, we would want to prevent using the basic DRF Serializers any more than we do right now, but preventing new DRF serializers via linting is more complex than anticipated.  This work can be revisited in the future once the platform is a bit more consistent.
+
+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.

docs/decisions/0026-standardize-permission-classes.rst

@@ -0,0 +1,122 @@
+Open edX ADR 0026: Standardize Permission Classes Across APIs
+=============================================================
+
+:Status: Accepted
+:Date: 2026-03-18
+:Deciders: API Working Group
+:Technical Story: Open edX REST API Standards - Permission standardization for security consistency
+
+Context
+-------
+
+Permissions are inconsistently applied across Open edX apps using custom decorators, inline role-based checks, and embedded authorization logic within views. This creates security gaps, makes it difficult for external systems to reliably determine access, and leads to duplicate authorization logic across multiple views.
+
+Decision
+--------
+
+We will standardize all Open edX REST APIs to use **DRF permission_classes** as the primary authorization mechanism.
+
+This ADR standardizes the **DRF integration surface** for authorization, not the underlying policy engine. DRF
+permission classes may delegate to legacy authorization checks or newer policy engines (such as Casbin) during
+phased migrations.
+
+Implementation requirements:
+
+* Use DRF permission_classes for all authorization logic instead of custom decorators.
+* Create reusable permission classes for common authorization patterns (course staff, global staff, etc.).
+* Replace inline role-based checks with explicit permission classes.
+* Ensure permission classes are properly documented and tested.
+* Maintain consistent permission patterns across similar endpoint types.
+* Keep the permission backend pluggable so DRF endpoints can migrate from legacy checks to newer policy engines
+  without changing endpoint-level authorization structure.
+
+Relevance in edx-platform
+-------------------------
+
+Current patterns that should be migrated:
+
+* **Enrollment API** (``/api/enrollment/v1/enrollment/{username},{course_id}``) uses custom inline role checks.
+* **User Tours API** (``/api/user_tours/v1/{username}``) mixes inline checks and permission_classes.
+* **Course orphan endpoints** (``^orphan/{settings.COURSE_KEY_PATTERN}$``) use functional views with inline permission logic.
+
+Code example (target permission usage)
+--------------------------------------
+
+**Example permission classes and APIView using DRF best practices:**
+
+.. code-block:: python
+
+   # permissions.py
+   from rest_framework.permissions import BasePermission
+
+   class IsCourseStaff(BasePermission):
+       """
+       Allows access only to course staff members.
+       """
+       def has_permission(self, request, view):
+           return request.user.is_authenticated and request.user.is_staff
+
+   class IsEnrollmentOwnerOrStaff(BasePermission):
+       """
+       Allows access to enrollment data for the user themselves or course staff.
+       """
+       def has_object_permission(self, request, view, obj):
+           return (
+               obj.user == request.user or
+               request.user.is_staff or
+               request.user.has_perm('course_staff', obj.course)
+           )
+
+   # views.py
+   from rest_framework.views import APIView
+   from rest_framework.response import Response
+   from rest_framework.permissions import IsAuthenticated
+   from .permissions import IsCourseStaff
+
+   class EnrollmentAPIView(APIView):
+       permission_classes = [IsAuthenticated, IsCourseStaff]
+
+       def get(self, request):
+           return Response({"detail": "Access granted"})
+
+Consequences
+------------
+
+Positive
+~~~~~~~~
+
+* Improves security consistency across all APIs.
+* Enhances predictability for external integrations.
+* Ensures reusable, testable authorization logic.
+* Simplifies security audits and permission reviews.
+* Enables centralized permission management.
+* Supports backend evolution (legacy checks to Casbin or other engines) without changing DRF endpoint contracts.
+
+Negative / Trade-offs
+~~~~~~~~~~~~~~~~~~~~~
+
+* Requires refactoring existing views with inline permission logic.
+* May need to create custom permission classes for complex authorization scenarios.
+* Initial development effort to identify and standardize permission patterns.
+* Requires careful bridging during migration so permission classes and underlying engines stay behaviorally
+  compatible while feature flags are in use.
+
+Alternatives Considered
+-----------------------
+
+* **Keep mixed permission approaches**: rejected due to security inconsistencies and maintenance burden.
+* **Use only decorators**: rejected because DRF permission_classes provide better integration with the framework.
+
+Rollout Plan
+------------
+
+1. Audit existing endpoints to identify inconsistent permission patterns.
+2. Create a library of standard permission classes for common use cases.
+3. Migrate high-security endpoints first (enrollment, user data, course management).
+4. Add comprehensive tests for permission classes and their usage.
+5. Update API documentation to clearly specify permission requirements.
+
+References
+----------
+
+* Open edX REST API Standards: "Permissions" recommendations for security consistency.