diff --git a/docs/decisions/0003-instructor-dashboard-rest-api-architecture.rst b/docs/decisions/0003-instructor-dashboard-rest-api-architecture.rst new file mode 100644 index 0000000..8752228 --- /dev/null +++ b/docs/decisions/0003-instructor-dashboard-rest-api-architecture.rst @@ -0,0 +1,277 @@ +ADR-0003 Instructor Dashboard REST API Architecture +=================================================== + +Decision +-------- + +Implement unified Instructor Dashboard REST API with service orchestration +pattern organizing 90 endpoints across 12 functional domains. + +Terminology +----------- + +**Services**: The Django apps and modules that each endpoint implementation will interact with to fulfill requests. This documents backend dependencies. + +**Status**: + - **Missing**: No existing endpoint provides this functionality + - **Partial**: An existing endpoint provides similar functionality but requires modification + - **Exists**: An existing endpoint fully provides this functionality + +API Endpoints +------------- + +Course Information API +^^^^^^^^^^^^^^^^^^^^^^ + +While ``/api/courses/v1/`` provides learner-facing course information, these instructor-specific endpoints provide administrative data (enrollment counts by mode, instructor tasks, pricing management) that require instructor permissions. + ++--------+---------------------------------------------------------------+---------------------------------------------+-----------+---------------------------------------------+-------------------------------------------------------------------------+ +| Method | Endpoint | Services | Status | Existing API Path | Description | ++========+===============================================================+=============================================+===========+=============================================+=========================================================================+ +| GET | /api/instructor/v1/courses/{course_key} | instructor, xmodule.modulestore | Missing | N/A | Retrieve course metadata, enrollment counts, permissions, and nav config | ++--------+---------------------------------------------------------------+---------------------------------------------+-----------+---------------------------------------------+-------------------------------------------------------------------------+ +| GET | /api/instructor/v1/courses/{course_key}/instructor_tasks | instructor_task | Partial | /api/instructor/v1/tasks/{course_id} | List background tasks for the course | ++--------+---------------------------------------------------------------+---------------------------------------------+-----------+---------------------------------------------+-------------------------------------------------------------------------+ +| GET | /api/instructor/v1/courses/{course_key}/modes | course_modes | On Hold | N/A | Retrieve enrollment modes and pricing for the course | ++--------+---------------------------------------------------------------+---------------------------------------------+-----------+---------------------------------------------+-------------------------------------------------------------------------+ +| PATCH | /api/instructor/v1/courses/{course_key}/modes/{mode_id}/price | course_modes | On Hold | N/A | Update pricing for a specific enrollment mode | ++--------+---------------------------------------------------------------+---------------------------------------------+-----------+---------------------------------------------+-------------------------------------------------------------------------+ + +Membership Management API +^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``GET /enrollments`` endpoint may return large datasets (thousands to hundreds of thousands of entries). Implementation must include pagination and performance optimization. + ++--------+--------------------------------------------------------------------+--------------------------------+-----------+-------------------------------------------------------------------+----------------------------------------------------------------------------------------------+ +| Method | Endpoint | Services | Status | Existing API Path | Description | ++========+====================================================================+================================+===========+===================================================================+==============================================================================================+ +| GET | /api/instructor/v1/courses/{course_key}/enrollments | enrollments, student | Missing | N/A | List all enrollments in the course (supports filtering by username, email) | ++--------+--------------------------------------------------------------------+--------------------------------+-----------+-------------------------------------------------------------------+----------------------------------------------------------------------------------------------+ +| POST | /api/instructor/v1/courses/{course_key}/enrollments | enrollments, student | Partial | /courses/{course_id}/instructor/api/students_update_enrollment | Enroll or unenroll a single student | ++--------+--------------------------------------------------------------------+--------------------------------+-----------+-------------------------------------------------------------------+----------------------------------------------------------------------------------------------+ +| DELETE | /api/instructor/v1/courses/{course_key}/enrollments | enrollments, student | Missing | N/A | Unenroll student(s) specified by query parameters | ++--------+--------------------------------------------------------------------+--------------------------------+-----------+-------------------------------------------------------------------+----------------------------------------------------------------------------------------------+ +| POST | /api/instructor/v1/courses/{course_key}/enrollments/batch | bulk_enroll, bulk_email | Partial | /courses/{course_id}/instructor/api/register_and_enroll_students | Bulk enroll/unenroll students (auto-register if needed, send email notification) | ++--------+--------------------------------------------------------------------+--------------------------------+-----------+-------------------------------------------------------------------+----------------------------------------------------------------------------------------------+ +| POST | /api/instructor/v1/courses/{course_key}/enrollments/csv_upload | bulk_enroll, util | Missing | N/A | Upload CSV file to bulk enroll/unenroll students | ++--------+--------------------------------------------------------------------+--------------------------------+-----------+-------------------------------------------------------------------+----------------------------------------------------------------------------------------------+ +| GET | /api/instructor/v1/courses/{course_key}/roles/ | student.auth | Missing | N/A | List all users with assigned roles in the course (supports filtering by role_type) | ++--------+--------------------------------------------------------------------+--------------------------------+-----------+-------------------------------------------------------------------+----------------------------------------------------------------------------------------------+ +| POST | /api/instructor/v1/courses/{course_key}/roles/{username} | student.auth | Partial | /courses/{course_id}/instructor/api/modify_access | Grant a course role to a user (role specified in request body) | ++--------+--------------------------------------------------------------------+--------------------------------+-----------+-------------------------------------------------------------------+----------------------------------------------------------------------------------------------+ +| DELETE | /api/instructor/v1/courses/{course_key}/roles/{username} | student.auth | Missing | N/A | Revoke a course role from a user (role specified in request body) | ++--------+--------------------------------------------------------------------+--------------------------------+-----------+-------------------------------------------------------------------+----------------------------------------------------------------------------------------------+ +| GET | /api/instructor/v1/courses/{course_key}/forum/members | discussion, student.auth | Partial | /courses/{course_id}/instructor/api/list_forum_members | List users with forum moderation roles | ++--------+--------------------------------------------------------------------+--------------------------------+-----------+-------------------------------------------------------------------+----------------------------------------------------------------------------------------------+ +| POST | /api/instructor/v1/courses/{course_key}/forum/members | discussion, student.auth | Partial | /courses/{course_id}/instructor/api/update_forum_role_membership | Grant forum moderation role to users | ++--------+--------------------------------------------------------------------+--------------------------------+-----------+-------------------------------------------------------------------+----------------------------------------------------------------------------------------------+ +| DELETE | /api/instructor/v1/courses/{course_key}/forum/members | discussion, student.auth | Missing | N/A | Revoke forum moderation role from users | ++--------+--------------------------------------------------------------------+--------------------------------+-----------+-------------------------------------------------------------------+----------------------------------------------------------------------------------------------+ + +Learner Administration API +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``GET /students/{username}`` endpoint will include ``enrollment_status`` and ``progress_url`` fields in the response. Separate endpoints for these single attributes are not needed. + ++--------+----------------------------------------------------------------------------------+--------------------------------------------------+-----------+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+ +| Method | Endpoint | Services | Status | Existing API Path | Description | ++========+==================================================================================+==================================================+===========+===============================================================================+=============================================================================================+ +| GET | /api/instructor/v1/courses/{course_key}/students | student, instructor | Missing | N/A | List all students enrolled in the course (supports filtering and pagination) | ++--------+----------------------------------------------------------------------------------+--------------------------------------------------+-----------+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+ +| GET | /api/instructor/v1/courses/{course_key}/students/{username} | student, instructor, enrollments | Partial | /courses/{course_id}/instructor/api/get_student_enrollment_status | Retrieve student info including enrollment status and progress URL | +| | | | | /courses/{course_id}/instructor/api/get_student_progress_url | | ++--------+----------------------------------------------------------------------------------+--------------------------------------------------+-----------+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+ +| POST | /api/instructor/v1/courses/{course_key}/students/{username}/reset_attempts | grades, xmodule.modulestore, instructor_task | Exists | /courses/{course_id}/instructor/api/reset_student_attempts | Reset student's attempts for a specific problem (requires problem location in body) | ++--------+----------------------------------------------------------------------------------+--------------------------------------------------+-----------+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+ +| POST | /api/instructor/v1/courses/{course_key}/students/{username}/reset_entrance_exam | grades, xmodule.modulestore | Exists | /courses/{course_id}/instructor/api/reset_student_attempts_for_entrance_exam | Reset student's entrance exam attempts and allow retake | ++--------+----------------------------------------------------------------------------------+--------------------------------------------------+-----------+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+ +| POST | /api/instructor/v1/courses/{course_key}/students/{username}/rescore_problem | grades, xmodule.modulestore, instructor_task | Exists | /courses/{course_id}/instructor/api/rescore_problem | Rescore a specific problem for a student (requires problem location in body) | ++--------+----------------------------------------------------------------------------------+--------------------------------------------------+-----------+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+ +| POST | /api/instructor/v1/courses/{course_key}/students/{username}/override_score | grades, xmodule.modulestore | Exists | /courses/{course_id}/instructor/api/override_problem_score | Manually override a student's score for a specific problem | ++--------+----------------------------------------------------------------------------------+--------------------------------------------------+-----------+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+ +| POST | /api/instructor/v1/courses/{course_key}/students/{username}/delete_state | student, xmodule.modulestore | Missing | N/A | Delete student's state/progress for a specific problem or unit | ++--------+----------------------------------------------------------------------------------+--------------------------------------------------+-----------+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+ +| POST | /api/instructor/v1/courses/{course_key}/problems/{problem_id}/reset_attempts_all | grades, xmodule.modulestore, instructor_task | Missing | N/A | Reset attempts for all students for a specific problem | ++--------+----------------------------------------------------------------------------------+--------------------------------------------------+-----------+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+ +| POST | /api/instructor/v1/courses/{course_key}/problems/{problem_id}/rescore_all | grades, xmodule.modulestore, instructor_task | Missing | N/A | Rescore a specific problem for all students in the course | ++--------+----------------------------------------------------------------------------------+--------------------------------------------------+-----------+-------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------+ + +Cohort Management API +^^^^^^^^^^^^^^^^^^^^^ + +The existing Cohort API at ``/api/cohorts/v1/`` provides full cohort management functionality. The instructor dashboard should use these existing endpoints rather than creating instructor-specific duplicates. See https://courses.edx.org/api-docs/ for complete API documentation. + +Discussion Management API +^^^^^^^^^^^^^^^^^^^^^^^^^ + +The existing Discussion API at ``/api/discussion/v1/`` provides full discussion management functionality including course topics (``GET /discussion/v2/course_topics/{course_id}``), settings (``GET/PATCH /discussion/v1/courses/{course_id}/settings``), and role management (``GET/POST /discussion/v1/courses/{course_id}/roles/{rolename}/``). The instructor dashboard should use these existing REST endpoints. Additionally, ``/api/discussions/v0/`` provides discussion provider configuration. No instructor-specific discussion endpoints are needed. + +Extensions & Deadlines API +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +These endpoints manage instructor-granted due date extensions (per-student deadline overrides), which are distinct from the learner-facing course deadline APIs at ``/api/course_experience/v1/``. Extensions are instructor-specific administrative operations requiring instructor permissions. + ++--------+-----------------------------------------------------------------------------------+----------------------------------+-----------+-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ +| Method | Endpoint | Services | Status | Existing API Path | Description | ++========+===================================================================================+==================================+===========+===================================================================+=========================================================================================+ +| GET | /api/instructor/v1/courses/{course_key}/graded_subsections | xmodule.modulestore, util | Missing | N/A | List all graded subsections/units with due dates (required for extension UI dropdowns) | ++--------+-----------------------------------------------------------------------------------+----------------------------------+-----------+-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ +| GET | /api/instructor/v1/courses/{course_key}/extensions | util.date_utils | Missing | N/A | List all due date extensions for a unit (requires unit usage_key in query params) | ++--------+-----------------------------------------------------------------------------------+----------------------------------+-----------+-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ +| POST | /api/instructor/v1/courses/{course_key}/extensions | util.date_utils | Partial | /courses/{course_id}/instructor/api/change_due_date | Grant a due date extension to a student for a specific unit | ++--------+-----------------------------------------------------------------------------------+----------------------------------+-----------+-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ +| PATCH | /api/instructor/v1/courses/{course_key}/extensions/{extension_id} | util.date_utils | Missing | N/A | Update an existing due date extension | ++--------+-----------------------------------------------------------------------------------+----------------------------------+-----------+-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ +| DELETE | /api/instructor/v1/courses/{course_key}/extensions/{extension_id} | util.date_utils | Partial | /courses/{course_id}/instructor/api/reset_due_date | Remove a due date extension (revert to original deadline) | ++--------+-----------------------------------------------------------------------------------+----------------------------------+-----------+-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ +| GET | /api/instructor/v1/courses/{course_key}/extensions/{username} | util.date_utils, student | Exists | /courses/{course_id}/instructor/api/show_student_extensions | List all due date extensions granted to a specific student | ++--------+-----------------------------------------------------------------------------------+----------------------------------+-----------+-------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + +**GET /api/instructor/v1/courses/{course_key}/graded_subsections** + +Returns an array of graded subsections/units with due dates, used to populate dropdown selectors in the Extensions UI. + +Response format:: + + [ + { + "graded_subsection": "Homework 1", + "block_id": "block-v1:edX+DemoX+Demo_Course+type@sequential+block@19a30717eff543078a5d94ae9d6c18a5" + }, + { + "graded_subsection": "Midterm Exam", + "block_id": "block-v1:edX+DemoX+Demo_Course+type@sequential+block@07bc32474380492cb34f76e5f9d9a135" + } + ] + +Data Export API +^^^^^^^^^^^^^^^ + +Report generation uses POST endpoints for each specific report type (e.g., ``/downloads/grade_report``). There is no generic ``POST /downloads`` endpoint - each report type has its own endpoint. + ++--------+-----------------------------------------------------------------------------------+----------------------------------------------+-----------+-------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ +| Method | Endpoint | Services | Status | Existing API Path | Description | ++========+===================================================================================+==============================================+===========+===================================================================+==================================================================================================+ +| GET | /api/instructor/v1/courses/{course_key}/downloads | instructor_task, util | Partial | /api/instructor/v1/reports/{course_id} | List all available report downloads (generated reports ready for download) | ++--------+-----------------------------------------------------------------------------------+----------------------------------------------+-----------+-------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ +| GET | /api/instructor/v1/courses/{course_key}/downloads/{download_id} | instructor_task, util | Missing | N/A | Retrieve metadata and download URL for a specific report | ++--------+-----------------------------------------------------------------------------------+----------------------------------------------+-----------+-------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ +| DELETE | /api/instructor/v1/courses/{course_key}/downloads/{download_id} | instructor_task, util | Missing | N/A | Delete a generated report file | ++--------+-----------------------------------------------------------------------------------+----------------------------------------------+-----------+-------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ +| POST | /api/instructor/v1/courses/{course_key}/downloads/student_profiles | instructor_task, student | Missing | N/A | Generate CSV report of student profile information | ++--------+-----------------------------------------------------------------------------------+----------------------------------------------+-----------+-------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ +| POST | /api/instructor/v1/courses/{course_key}/downloads/grade_report | instructor_task, grades | Exists | /courses/{course_id}/instructor/api/calculate_grades_csv | Generate CSV grade report for all enrolled students | ++--------+-----------------------------------------------------------------------------------+----------------------------------------------+-----------+-------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ +| POST | /api/instructor/v1/courses/{course_key}/downloads/problem_grade_report | instructor_task, grades | Exists | /courses/{course_id}/instructor/api/problem_grade_report | Generate CSV report of problem-level grades for all students | ++--------+-----------------------------------------------------------------------------------+----------------------------------------------+-----------+-------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ +| POST | /api/instructor/v1/courses/{course_key}/downloads/course_structure | instructor_task, xmodule.modulestore | Missing | N/A | Generate JSON/CSV export of course structure | ++--------+-----------------------------------------------------------------------------------+----------------------------------------------+-----------+-------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ +| POST | /api/instructor/v1/courses/{course_key}/downloads/survey_results | instructor_task, grades | Exists | /courses/{course_id}/instructor/api/get_course_survey_results | Generate CSV report of survey results | ++--------+-----------------------------------------------------------------------------------+----------------------------------------------+-----------+-------------------------------------------------------------------+--------------------------------------------------------------------------------------------------+ + +Bulk Email API +^^^^^^^^^^^^^^ + +No REST API currently exists for bulk email operations. The existing ``bulk_email`` module provides internal APIs but not RESTful endpoints. These instructor-specific endpoints will provide the first REST API for bulk email functionality. + ++--------+-----------------------------------------------------------------------------------+----------------------------------------------+-----------+-------------------------------------------------------------------+-------------------------------------------------------------------------------------------+ +| Method | Endpoint | Services | Status | Existing API Path | Description | ++========+===================================================================================+==============================================+===========+===================================================================+===========================================================================================+ +| GET | /api/instructor/v1/courses/{course_key}/bulk_email | bulk_email | Missing | N/A | List all sent bulk emails for the course | ++--------+-----------------------------------------------------------------------------------+----------------------------------------------+-----------+-------------------------------------------------------------------+-------------------------------------------------------------------------------------------+ +| POST | /api/instructor/v1/courses/{course_key}/bulk_email | bulk_email, instructor_task | Exists | /courses/{course_id}/instructor/api/send_email | Send bulk email to students (supports targeting by cohort, enrollment track, etc.) | ++--------+-----------------------------------------------------------------------------------+----------------------------------------------+-----------+-------------------------------------------------------------------+-------------------------------------------------------------------------------------------+ +| GET | /api/instructor/v1/courses/{course_key}/bulk_email/{email_id} | bulk_email | Missing | N/A | Retrieve details of a specific bulk email | ++--------+-----------------------------------------------------------------------------------+----------------------------------------------+-----------+-------------------------------------------------------------------+-------------------------------------------------------------------------------------------+ +| GET | /api/instructor/v1/courses/{course_key}/bulk_email/{email_id}/status | bulk_email, instructor_task | Partial | /courses/{course_id}/instructor/api/list_background_email_tasks | Get send status for a bulk email (pending, in-progress, completed) | ++--------+-----------------------------------------------------------------------------------+----------------------------------------------+-----------+-------------------------------------------------------------------+-------------------------------------------------------------------------------------------+ +| DELETE | /api/instructor/v1/courses/{course_key}/bulk_email/{email_id} | bulk_email | Missing | N/A | Cancel a pending bulk email or delete email record | ++--------+-----------------------------------------------------------------------------------+----------------------------------------------+-----------+-------------------------------------------------------------------+-------------------------------------------------------------------------------------------+ +| GET | /api/instructor/v1/courses/{course_key}/email_templates | bulk_email | Exists | /courses/{course_id}/instructor/api/list_email_content | List previously sent emails (serves as templates for new emails) | ++--------+-----------------------------------------------------------------------------------+----------------------------------------------+-----------+-------------------------------------------------------------------+-------------------------------------------------------------------------------------------+ + +Special Exams API +^^^^^^^^^^^^^^^^^ + +Proctoring functionality is provided by the ``edx-proctoring`` plugin. These endpoints provide instructor-facing operations for managing proctored exams, accommodations, and reviewing attempts. Consider whether these should be added to the proctoring plugin's API or kept in the instructor API for consistency. + ++--------+-----------------------------------------------------------------------------------+----------------------------------------------+-----------+-------------------------------------------------------------------+-------------------------------------------------------------------------------------------+ +| Method | Endpoint | Services | Status | Existing API Path | Description | ++========+===================================================================================+==============================================+===========+===================================================================+===========================================================================================+ +| GET | /api/instructor/v1/courses/{course_key}/special_exams | edx_proctoring, grades | Missing | N/A | List all proctored/timed exams in the course | ++--------+-----------------------------------------------------------------------------------+----------------------------------------------+-----------+-------------------------------------------------------------------+-------------------------------------------------------------------------------------------+ +| GET | /api/instructor/v1/courses/{course_key}/special_exams/{exam_id} | edx_proctoring, grades | Missing | N/A | Retrieve details and statistics for a specific special exam | ++--------+-----------------------------------------------------------------------------------+----------------------------------------------+-----------+-------------------------------------------------------------------+-------------------------------------------------------------------------------------------+ +| POST | /api/instructor/v1/courses/{course_key}/special_exams/{exam_id}/reset/{username} | edx_proctoring, InstructorService | Missing | N/A | Reset a student's proctored exam attempt | ++--------+-----------------------------------------------------------------------------------+----------------------------------------------+-----------+-------------------------------------------------------------------+-------------------------------------------------------------------------------------------+ +| GET | /api/instructor/v1/courses/{course_key}/special_exams/{exam_id}/attempts | edx_proctoring, grades | Partial | /courses/{course_id}/instructor/api/get_proctored_exam_results | List all attempts for a proctored exam with review status | ++--------+-----------------------------------------------------------------------------------+----------------------------------------------+-----------+-------------------------------------------------------------------+-------------------------------------------------------------------------------------------+ +| GET | /api/instructor/v1/courses/{course_key}/proctoring_settings | edx_proctoring | Missing | N/A | Retrieve proctoring configuration for the course | ++--------+-----------------------------------------------------------------------------------+----------------------------------------------+-----------+-------------------------------------------------------------------+-------------------------------------------------------------------------------------------+ +| PATCH | /api/instructor/v1/courses/{course_key}/proctoring_settings | edx_proctoring | Missing | N/A | Update proctoring settings for the course | ++--------+-----------------------------------------------------------------------------------+----------------------------------------------+-----------+-------------------------------------------------------------------+-------------------------------------------------------------------------------------------+ +| POST | /api/instructor/v1/courses/{course_key}/special_exams/{exam_id}/allowance | edx_proctoring, student | Missing | N/A | Grant time extension or accommodation for a student on a proctored exam | ++--------+-----------------------------------------------------------------------------------+----------------------------------------------+-----------+-------------------------------------------------------------------+-------------------------------------------------------------------------------------------+ + +Certificates API +^^^^^^^^^^^^^^^^ + +While ``/api/certificates/v0/`` provides learner-facing certificate retrieval, these instructor-specific endpoints provide administrative operations (certificate generation, allowlist management, bulk operations) that require instructor permissions. + ++--------+-----------------------------------------------------------------------------------+----------------------------------------------+-----------+--------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------+ +| Method | Endpoint | Services | Status | Existing API Path | Description | ++========+===================================================================================+==============================================+===========+==========================================================================+====================================================================================================+ +| GET | /api/instructor/v1/courses/{course_key}/certificates | certificates | Partial | /courses/{course_id}/instructor/api/get_issued_certificates | List issued certificates for the course | ++--------+-----------------------------------------------------------------------------------+----------------------------------------------+-----------+--------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------+ +| POST | /api/instructor/v1/courses/{course_key}/certificates/generate | certificates, instructor_task | Exists | /courses/{course_id}/instructor/api/start_certificate_generation | Generate certificates for all eligible students | ++--------+-----------------------------------------------------------------------------------+----------------------------------------------+-----------+--------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------+ +| POST | /api/instructor/v1/courses/{course_key}/certificates/generate/{username} | certificates, student | Missing | N/A | Generate certificate for a specific student | ++--------+-----------------------------------------------------------------------------------+----------------------------------------------+-----------+--------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------+ +| POST | /api/instructor/v1/courses/{course_key}/certificates/generate_bulk | certificates, instructor_task | Exists | /courses/{course_id}/instructor/api/generate_bulk_certificate_exceptions | Bulk generate certificates for students on the allowlist | ++--------+-----------------------------------------------------------------------------------+----------------------------------------------+-----------+--------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------+ +| GET | /api/instructor/v1/courses/{course_key}/certificates/allowlist | certificates | Missing | N/A | List students on the certificate allowlist (students who can receive certs despite not passing) | ++--------+-----------------------------------------------------------------------------------+----------------------------------------------+-----------+--------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------+ +| POST | /api/instructor/v1/courses/{course_key}/certificates/allowlist | certificates, student | Partial | /courses/{course_id}/instructor/api/certificate_exception_view | Add student(s) to certificate allowlist | ++--------+-----------------------------------------------------------------------------------+----------------------------------------------+-----------+--------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------+ +| DELETE | /api/instructor/v1/courses/{course_key}/certificates/allowlist | certificates | Missing | N/A | Remove student(s) from certificate allowlist | ++--------+-----------------------------------------------------------------------------------+----------------------------------------------+-----------+--------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------+ +| GET | /api/instructor/v1/courses/{course_key}/certificates/{certificate_id}/status | certificates | Missing | N/A | Get generation status for a specific certificate | ++--------+-----------------------------------------------------------------------------------+----------------------------------------------+-----------+--------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------+ + +Open Response Assessment API +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ``ora_staff_grader`` module provides ORA grading functionality. These endpoints expose instructor-facing operations for managing ORA submissions, overriding grades, and resetting attempts. + ++--------+-------------------------------------------------------------------------------------------------+----------------------------------------------+-----------+--------------------------------------------------------+-------------------------------------------------------------------------------------------+ +| Method | Endpoint | Services | Status | Existing API Path | Description | ++========+=================================================================================================+==============================================+===========+========================================================+===========================================================================================+ +| GET | /api/instructor/v1/courses/{course_key}/ora | ora_staff_grader, xmodule.modulestore | Missing | N/A | List all ORA problems in the course | ++--------+-------------------------------------------------------------------------------------------------+----------------------------------------------+-----------+--------------------------------------------------------+-------------------------------------------------------------------------------------------+ +| GET | /api/instructor/v1/courses/{course_key}/ora/{ora_id} | ora_staff_grader, xmodule.modulestore | Missing | N/A | Retrieve details and statistics for a specific ORA problem | ++--------+-------------------------------------------------------------------------------------------------+----------------------------------------------+-----------+--------------------------------------------------------+-------------------------------------------------------------------------------------------+ +| GET | /api/instructor/v1/courses/{course_key}/ora/{ora_id}/submissions | ora_staff_grader | Missing | N/A | List all student submissions for an ORA problem | ++--------+-------------------------------------------------------------------------------------------------+----------------------------------------------+-----------+--------------------------------------------------------+-------------------------------------------------------------------------------------------+ +| GET | /api/instructor/v1/courses/{course_key}/ora/{ora_id}/submissions/{submission_id} | ora_staff_grader | Missing | N/A | Retrieve details for a specific ORA submission | ++--------+-------------------------------------------------------------------------------------------------+----------------------------------------------+-----------+--------------------------------------------------------+-------------------------------------------------------------------------------------------+ +| POST | /api/instructor/v1/courses/{course_key}/ora/{ora_id}/submissions/{submission_id}/override_grade | ora_staff_grader | Missing | N/A | Manually override the grade for an ORA submission | ++--------+-------------------------------------------------------------------------------------------------+----------------------------------------------+-----------+--------------------------------------------------------+-------------------------------------------------------------------------------------------+ +| POST | /api/instructor/v1/courses/{course_key}/ora/{ora_id}/submissions/{submission_id}/reset | ora_staff_grader | Partial | /courses/{course_id}/instructor/api/export_ora2_data | Reset an ORA submission (allow student to resubmit) | ++--------+-------------------------------------------------------------------------------------------------+----------------------------------------------+-----------+--------------------------------------------------------+-------------------------------------------------------------------------------------------+ + +Analytics API +^^^^^^^^^^^^^ + +The analytics dashboard URL will be included in the ``GET /api/instructor/v1/courses/{course_key}`` response as ``analytics_dashboard_url``. + ++--------+--------------------------------------------------------------------------+----------------------------------------------+-----------+----------------------------+-------------------------------------------------------------------------------------------+ +| Method | Endpoint | Services | Status | Existing API Path | Description | ++========+==========================================================================+==============================================+===========+============================+===========================================================================================+ +| GET | /api/instructor/v1/courses/{course_key}/analytics/summary | instructor_analytics, student | Missing | N/A | Retrieve high-level analytics summary (enrollment, engagement, performance metrics) | ++--------+--------------------------------------------------------------------------+----------------------------------------------+-----------+----------------------------+-------------------------------------------------------------------------------------------+ +| GET | /api/instructor/v1/courses/{course_key}/analytics/engagement | instructor_analytics | Missing | N/A | Retrieve student engagement metrics (activity, time spent, participation) | ++--------+--------------------------------------------------------------------------+----------------------------------------------+-----------+----------------------------+-------------------------------------------------------------------------------------------+ +| GET | /api/instructor/v1/courses/{course_key}/analytics/performance | instructor_analytics, grades | Missing | N/A | Retrieve performance metrics (grades distribution, problem completion rates) | ++--------+--------------------------------------------------------------------------+----------------------------------------------+-----------+----------------------------+-------------------------------------------------------------------------------------------+ +| GET | /api/instructor/v1/courses/{course_key}/analytics/enrollment | instructor_analytics, enrollments | Missing | N/A | Retrieve enrollment statistics over time (trends, demographics) | ++--------+--------------------------------------------------------------------------+----------------------------------------------+-----------+----------------------------+-------------------------------------------------------------------------------------------+