docs: instructor grading api spec

lms/djangoapps/instructor/docs/decisions/0001-course-info-api-spec.rst

@@ -0,0 +1,66 @@
+Instructor Course Information API Specification
+-----------------------------------------------
+
+Status
+======
+
+**Accepted** *2025-10-30*
+
+Context
+=======
+
+The instructor dashboard requires comprehensive course metadata, enrollment statistics, user
+permissions, and navigation configuration. This information was previously scattered across
+multiple endpoints, requiring multiple round-trip requests and complex client-side data
+aggregation for MFEs.
+
+Decisions
+=========
+
+#. **Consolidated Course Metadata Endpoint**
+
+   Create ``GET /api/instructor/v2/courses/{course_id}`` that returns comprehensive course
+   information in a single request, including course identity, timing, enrollment statistics,
+   user permissions, dashboard tab configuration, and operational information.
+
+#. **Permission-Based Tab Configuration**
+
+   Server-side logic determines which dashboard tabs the current user can access based on
+   their roles, course features, and system configuration. Tabs are returned with URLs
+   pointing to the appropriate MFE routes.
+
+#. **Serializer-Based Business Logic**
+
+   Use Django REST Framework serializers (``CourseInformationSerializer``) to encapsulate
+   all business logic for data gathering, permission checks, enrollment queries, and
+   formatting. Keep views thin.
+
+#. **OpenAPI Specification**
+
+   Maintain an OpenAPI specification at ``../references/instructor-v2-course-info-spec.yaml`` to guide implementation. This static specification serves as a reference during development, but ``/api-docs/`` is the source of truth for what is actually deployed. Once implementation is complete and the endpoints are live in ``/api-docs/``, the static spec file will be deleted to avoid maintaining outdated documentation.
+
+Consequences
+============
+
+Positive
+~~~~~~~~
+
+* Single request replaces multiple round-trips, reducing latency for MFE page loads
+* Centralized business logic ensures consistent permission checks and data formatting
+* Simplified client code with all course information available in one call
+* OpenAPI specification enables type-safe client generation
+
+Negative
+~~~~~~~~
+
+* Larger response payload (though offset by eliminating multiple requests)
+* Some over-fetching when clients don't need all information
+* Permission-based data prevents simple course-level caching
+* Enrollment queries and permission checks run on every request
+
+References
+==========
+
+* OpenAPI Specification: ``../references/instructor-v2-course-info-spec.yaml``
+* Implementation: ``lms/djangoapps/instructor/views/api_v2.py``
+* Live API Documentation: ``/api-docs/``

lms/djangoapps/instructor/docs/decisions/0002-instructor-grading-api-spec.rst

@@ -0,0 +1,77 @@
+Instructor Grading API Specification
+-------------------------------------
+
+Status
+======
+
+**Draft** (=> **Provisional**)
+
+Context
+=======
+
+The instructor dashboard is being migrated to a Micro-Frontend (MFE) architecture, which requires RESTful API endpoints. The current implementation provides grading operations (reset attempts, rescore, override scores, delete state) through legacy endpoints.
+
+The MFE migration requires a modern, RESTful API with consistent URL patterns, clear synchronous vs asynchronous behavior, comprehensive task monitoring, and proper documentation. These operations need to support both single-learner (synchronous) and all-learners (asynchronous) execution models.
+
+Decisions
+=========
+
+#. **RESTful Resource-Oriented Design**
+
+   Use resource-oriented URLs: ``/api/instructor/v2/courses/{course_key}/{problem}/grading/{resource}``
+
+   Use appropriate HTTP methods:
+
+   * ``GET`` for read operations (learner info, problem metadata, task status)
+   * ``POST`` for actions (reset attempts, rescore)
+   * ``PUT`` for replacements (score overrides)
+   * ``DELETE`` for removals (delete learner state)
+
+#. **Synchronous vs Asynchronous Execution**
+
+   * Operations targeting a single learner (with ``learner`` parameter) execute synchronously
+     and return ``200 OK`` with immediate results (< 5s typical)
+   * Operations targeting all learners (no ``learner`` parameter) queue a background task
+     and return ``202 Accepted`` with task tracking information
+   * Provide task status endpoint: ``GET /api/instructor/v2/courses/{course_key}/tasks/{task_id}``
+
+#. **Clear Operation Semantics**
+
+   * **Reset Attempts**: Resets counter to zero, preserves answers/state
+   * **Delete State**: Permanently removes all learner data (requires ``learner`` parameter)
+   * **Rescore**: Re-evaluates submissions with current grading logic (supports ``only_if_higher``)
+   * **Override Score**: Manually sets specific score (requires ``learner`` parameter)
+
+#. **Consistent Response Formats**
+
+   * Synchronous operations return ``SyncOperationResult`` with success, learner, problem_location, message
+   * Asynchronous operations return ``AsyncOperationResult`` with task_id, status_url, scope
+   * Task status responses include task_id, state, progress, result/error, timestamps
+
+#. **OpenAPI Specification**
+
+   Maintain an OpenAPI specification at ``../references/instructor-v2-grading-api-spec.yaml`` to guide implementation. This static specification serves as a reference during development, but ``/api-docs/`` is the source of truth for what is actually deployed. Once implementation is complete and the endpoints are live in ``/api-docs/``, the static spec file will be deleted to avoid maintaining outdated documentation.
+
+Consequences
+============
+
+Positive
+~~~~~~~~
+
+* Consistent URL patterns and response formats make the API predictable
+* Explicit sync/async behavior allows proper UI feedback
+* OpenAPI specification enables automated validation, testing, and type-safe client generation
+* Resource-oriented design makes it easy to add new operations
+
+Negative
+~~~~~~~~
+
+* Existing clients using legacy endpoints need to be updated
+* Dual maintenance during transition period
+* Developers familiar with legacy endpoints need to learn new patterns
+
+References
+==========
+
+* OpenAPI Specification: ``../references/instructor-v2-grading-api-spec.yaml``
+* Live API Documentation: ``/api-docs/``