Feature/37905 instructor dashboard grading post endpoints

[brianjbuck-wgu]

No description provided.

[openedx-webhooks]

Thanks for the pull request, @brianjbuck-wgu!

This repository is currently maintained by @openedx/wg-maintenance-openedx-platform.

Once you've gone through the following steps feel free to tag them in a comment and let them know that your changes are ready for engineering review.

🔘 Get product approval

If you haven't already, check this list to see if your contribution needs to go through the product review process.

• If it does, you'll need to submit a product proposal for your contribution, and have it reviewed by the Product Working Group.
  • This process (including the steps you'll need to take) is documented here.
• If it doesn't, simply proceed with the next step.

🔘 Provide context

To help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:

• Dependencies

  This PR must be merged before / after / at the same time as ...

• Blockers

  This PR is waiting for OEP-1234 to be accepted.

• Timeline information

  This PR must be merged by XX date because ...

• Partner information

  This is for a course on edx.org.

• Supporting documentation
• Relevant Open edX discussion forum threads

🔘 Get a green build

If one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green.

Details

---

Where can I find more information?

If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources:

• Overview of Review Process for Community Contributions
• Pull Request Status Guide
• Making changes to your pull request

When can I expect my changes to be merged?

Our goal is to get community contributions seen and reviewed as efficiently as possible.

However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:

• The size and impact of the changes that it introduces
• The need for product review
• Maintenance status of the parent repository

💡 As a result it may take up to several weeks or months to complete a review and merge your PR.

[Copilot]

Pull request overview

Adds new Instructor API v2 “grading” endpoints intended to support instructor dashboard workflows for resetting attempts, deleting learner state, rescoring, and overriding scores.

Changes:

• Introduces new grading endpoints in Instructor API v2 for reset attempts, delete state, rescore, and score override operations (sync + async patterns).
• Adds new v2 serializers for sync/async operation results and the score override request body.
• Adds test coverage for the new endpoints and updates v2 URL routing.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
lms/djangoapps/instructor/views/serializers_v2.py	Adds serializers for grading operation responses and score override request validation.
lms/djangoapps/instructor/views/api_v2.py	Implements new grading endpoints plus helper functions for parsing and learner resolution.
lms/djangoapps/instructor/views/api_urls.py	Wires new grading endpoints into the Instructor API v2 URLconf.
lms/djangoapps/instructor/tests/views/test_api_v2.py	Adds endpoint tests for reset attempts, delete state, rescore, and score override behaviors.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[diana-villalvazo-wgu]

can you provide a quick summary on what does each endpoint?
For example if we are on a single learner view we should be able to rescore learner submission for a specific problem and with another action rescore only if the score improves, with the rescore endpoint i can do both? which param should i pass to differentiate them?

[diana-villalvazo-wgu]

can we keep same attributes and logic from:

• http://local.openedx.io:8000/courses/course-v1:OpenedX+DemoX+DemoCourse/instructor/api/rescore_problem
• http://local.openedx.io:8000/courses/course-v1:OpenedX+DemoX+DemoCourse/instructor/api/override_problem_score
• http://local.openedx.io:8000/courses/course-v1:OpenedX+DemoX+DemoCourse/instructor/api/reset_student_attempts

I think what needs to be changed/improved is the response after frontend makes the POST right not it throws a string directly, we should handle it in a better structure following json or idk

[brianjbuck-wgu]

can you provide a quick summary on what does each endpoint? For example if we are on a single learner view we should be able to rescore learner submission for a specific problem and with another action rescore only if the score improves, with the rescore endpoint i can do both? which param should i pass to differentiate them?

@diana-villalvazo-wgu: Here's a summary of each grading endpoint:

v2 Endpoint	Method	Description
{problem}/grading/attempts/reset?learner=<id>	POST	Reset a single learner's attempt count to 0. Synchronous — returns 200.
{problem}/grading/attempts/reset	POST	Reset all learners' attempts. Queues a background task — returns 202 with task_id.
{problem}/grading/state?learner=<id>	DELETE	Delete a learner's entire state for the problem (irreversible). Synchronous — returns 200.
{problem}/grading/scores/rescore?learner=<id>	POST	Rescore a single learner's submission. Queues a background task — returns 202.
{problem}/grading/scores/rescore?learner=<id>&only_if_higher=true	POST	Rescore only if higher — same endpoint, add only_if_higher=true. Only updates if new score is higher.
{problem}/grading/scores/rescore	POST	Rescore all learners for the problem. Also supports only_if_higher=true. Returns 202.
{problem}/grading/scores?learner=<id>	PUT	Override a learner's score. Accepts JSON body {"score": 8.5}. Returns 202.

All paths are prefixed with /api/instructor/v2/courses/{course_id}/.

So yes, the rescore endpoint handles both cases — the only_if_higher query parameter is what differentiates "rescore" from "rescore only if score improves."

[brianjbuck-wgu]

can we keep same attributes and logic from:

• http://local.openedx.io:8000/courses/course-v1:OpenedX+DemoX+DemoCourse/instructor/api/rescore_problem
• http://local.openedx.io:8000/courses/course-v1:OpenedX+DemoX+DemoCourse/instructor/api/override_problem_score
• http://local.openedx.io:8000/courses/course-v1:OpenedX+DemoX+DemoCourse/instructor/api/reset_student_attempts

I think what needs to be changed/improved is the response after frontend makes the POST right not it throws a string directly, we should handle it in a better structure following json or idk

@diana-villalvazo-wgu:

Yes, the v2 endpoints use the exact same underlying logic as the v1 endpoints:

• reset_student_attempts → calls enrollment.reset_student_attempts() (same as v1)
• rescore_problem → calls task_api.submit_rescore_problem_for_student() / submit_rescore_problem_for_all_students() (same as v1)
• override_problem_score → calls task_api.submit_override_score() (same as v1)

The main improvement is exactly what you described. Instead of returning raw strings, all v2 responses are structured JSON:

Synchronous (200):

 {"success": true, "learner": "john", "message": "Attempts reset successfully"}

Asynchronous (202):

{"task_id": "abc-123", "status_url": "/api/instructor/v2/courses/.../tasks/abc-123", "scope": {"learners": "john", "problem_location": "block-v1:..."}}

Errors (4xx):

{"error": "Learner not found"}