Page tree

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Add the new _aplus_ parameter for the submission language and group


  • Adding student groups to the API should be straightforward. We need these API endpoints:
    • Fetch the user's (the user who is authenticated) own student groups in the course instance: /api/v2/courses/ID/mygroups/
      • Data about group members: user's full name, user ID
      • No student IDs are provided here since students should not normally see other students' IDs
    • Fetch all student groups in the course instance (accessible by teachers): /api/v2/courses/ID/groups/
      • Full details about the group members
  • Exercise submissions
    • Students must be allowed to HTTP POST new submissions to the API.
    • New endpoint for creating submissions that are sent to the exercise grader: /api/v2/exercises/ID/submissions/submit/
      • The submission data is included in POST parameters. The submission data must use the keys for different fields that are configured in the exercise config.yaml file (in the course repository). The POST parameters may include files.
      • The endpoint /api/v2/exercises/ID/ provides information about the exercise including the specification of the submission form (i.e., the keys for the submission data fields like a file to submit).
      • The POST data should always include the field "__aplus__={"group": groupID, "lang": "en"}" (in the old version, the parameter was "_aplus_group" without the aplus JSON object) for selecting the group of the submission. Its value is the group ID. The IDs of available groups can be retrieved from the endpoint /api/v2/courses/ID/mygroups/. If the user submits alone, the value zero must be used for "_aplus_the group". If the "_aplus_group" field group ID is not defined and the user has selected a group in the course level in the A+ course web page, then A+ would use that group for the submission, which would be confusing since the user can't see the A+ web page while submitting through the API. NB: the group selected with "_aplus_ group " must be the user's own group. If the ID belongs to a group that the user is not a member of, the group is ignored and the submission is made for the user alone.
      • The POST data may also language of the submission (in multilingual courses like Programming 1) is defined with the same __aplus__ object: "__aplus__={"group": groupID, "lang": "en"}". If the grader supports different languages, it should generate feedback in the given language.
      • The POST data must NOT include the field "__grader_lang=en" that selects the language (English/Finnish) for the grader and feedback. It is at least used in questionnaires by the MOOC-Graderhas previously been used by A+ as a hacky fix to select the questionnaire feedback language.
      • Examples of testing the API with curl in the command line (with and without an uploaded file) (the authorization token must be changed to the real value and likewise, the exercise IDs as well as submission data and files can be changed. The file path "" refers to a local file in your computer.):
      • curl -v -X POST 'http://localhost:8000/api/v2/exercises/10/submissions/submit/' -d 'somekey=1&myrandom=2' -H 'Authorization: Token b6a6debaaf94b7a7b65fa5b2cead10eec6cb4516'
      • curl -v -X POST 'http://localhost:8000/api/v2/exercises/21/submissions/submit/' -H 'Authorization: Token 94ad2abfc128a3da3b0541fbfea981bc62becd56' -F "'__aplus_grader_lang=en{" -F "_aplus_group=1" group": 1, "lang": "en"}'  -F ''
    • The endpoint /api/v2/exercises/ID/submissions/submit/ returns the HTTP response with status 201 Created if the new submission was successfully stored in A+. The response includes the Location header that points to the new submission, e.g., http://localhost:8000/api/v2/submissions/ID/. The submission endpoint returns info about the submission, e.g., the feedback, points and the status. If the status is not "ready", the submission has not been graded yet (or it has failed due to some error).
    • The grading of the submission may fail. The submission may end up in the error status, or it could be stuck in the initialized or waiting statuses. If the submission data does not included the required fields, the grader rejects it and the submission receives the rejected status.
    • Return values for the /api/v2/exercises/ID/submissions/submit/ endpoint:
      • Success: status code HTTP 201 Created and an empty response body. The response has the Location header pointing to the new submission.
      • submission created in A+ but there are errors in grading: status code HTTP 201 Created and JSON response {"errors": ["some message"]} (list of error messages). The response has the Location header pointing to the new submission.
      • student is not allowed to submit (e.g., deadlines or max submissions limit): HTTP 400 Bad request and JSON response {"errors": ["some message"]} (list of error messages)
      • authentication failed: HTTP 403 Forbidden and JSON response  {"detail": "some message"} (a single error string)
      • A+ can not create the submission in the database: HTTP 500 Internal error and JSON response {"detail": "some message"}
      • something else? The Django REST framework may have some built-in validation or something else that would probably use the "detail" key for the error message.
    • The following bullets are comments about the old API before the changes:
      • Currently, only exercise grading service is authorized for this endpoint:
      • The same file contains other API endpoints that are related to the A+ grader protocol and manual grading:
        • ExerciseViewSet grader_detail: part of the grader protocol for the mooc-grader. Creates a new submission and grades it. Only one submitter (student). No submission files. This endpoint corresponds to the submission_url parameter of the grader protocol when the exercise description is fetched with HTTP GET.
        • ExerciseSubmissionsViewSet create: only allowed for teachers. Creates a new submission and grades it (basically, it can be used for storing the results of manual grading). Can set feedback, assistant feedback and submission time too. No submission files.
        • SubmissionViewSet grader_detail: part of the grader protocol for the mooc-grader. Grades an existing submission (used in normal asynchronous grading). This endpoint corresponds to the submission_url parameter of the grader protocol when the submission is sent to the exercise service for grading with HTTP POST.
      • The existing endpoint does not support group submissions. The new endpoint should receive the group ID in the POST parameters so that the group members can be added to the submission. Normal submissions in the web page include the submitting user and the group ID in the POST data.
      • Submitting files must be supported.
      • The API must check if the user is allowed to submit to the exercise (like in normal submissions in the web UI).
      • It is  best to create yet another new API endpoint for this. The other old endpoints are intended for different usecases
  • Authentication
    • The existing user tokens can be used in the API for authenticating the user. Users can see their token in their A+ profile page (accessed from the top-right user menu).
    • The API endpoints take the token from the HTTP request Authorization header in the format "Authorization: Token 94ad2abfc128a3da3b0541fbfea981bc62becd56".
    • If we can't implement any better authentication method, then users could manually copy-paste their token from the A+ web page into some menu in the IntelliJ plugin. The plugin could store the token so that it is only set up once.
    • The user tokens are specific to each user and they do not automatically expire. We should avoid leaking these tokens to any malicious outsiders since they are basically like passwords.
    • Improvements to the authentication:
      • Users should not see or manually enter the token in the IntelliJ plugin. Users should be able to log into A+ from the plugin by entering their user name and password.
      • Is it possible to use a web view (browser) inside IntelliJ IDEA in such a way that the user would log into A+ inside IntelliJ and IntelliJ could then capture the user's token from A+ and store the token? The user would not need to manually copy-paste the token.
      • Because A+ typically uses single sign-on (Shibboleth, HAKA federation), it might not be possible to implement an API endpoint that takes the username and password as input and returns the API user token.