NAV
shell

Introduction

Note: API is still a work in progress.

Most of the API is restricted to faculty, however the Students section can be used by students or faculty. API provides an alternative way of interacting with Submitty. It facilitates testing, helps system administrators to modify resources and enables users to create customized frontends.

Note that as we rely on the Authorization header information to authenticate users, please make sure that you have a correct Apache configuration file as specified in Installation Version Notes: v19.06.02.

Requests

Submitty supports requests using the following two content-types:

while anything involving files should use:

All endpoints use the /api path off the base Submitty URL, followed by the specific endpoint for the API in question.

Responses

Example of a success JSON response:

{
  "status": "success",
  "data": null
}

Example of a fail JSON response:

{
  "status": "fail",
  "message": "Did not specify gradeable"
}

All API responses will be returned as application/json and conform to a modified version of the JSend specification. A response returned from the server is expected to be one of the following three response types.

Type Description Required Keys Optional Keys
success All went well, and (usually) some data was returned status, data
fail There was a problem with the data submitted, or some pre-condition of the API call wasn't satisfied status, message data
error An error occurred in processing the request, i.e. an exception was thrown status, message data, code

Authentication

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "Authorization: my_token"

Make sure to replace my_token with your API token, or API will return JSON like this:

{
    "status": "fail",
    "message": "Unauthenticated access. Please log in."
}

Submitty uses JSON Web Tokens to allow access to the API. You can obtain your API token through the following endpoint.

Kittn expects for the API token to be included in all API requests to the server in a header that looks like the following:

Authorization: my_token

Get Token

curl -X POST \
  <base_url>/api/token \
  -F user_id=instructor \
  -F password=instructor

The above command returns JSON structured like this:

{
    "status": "success",
    "data": {
        "token": "a long string"
    }
}

Note that every time you request a new token, the previous token will be invalidated.

HTTP Request

POST /api/token

Parameters

Parameter Description
user_id User's unique ID
password User's password

Invalidate Token

curl -X POST \
  <base_url>/api/token/invalidate \
  -F user_id=instructor \
  -F password=instructor

The endpoint invalidates the token you requested before.

HTTP Request

POST /api/token/invalidate

Parameters

Parameter Description
user_id User's unique ID
password User's password

Courses

Get Courses

curl --request GET \
  --url <base_url>/api/courses \
  --header 'Authorization: my_token'

The above command returns JSON structured like this:

{
    "status": "success",
    "data": {
        "unarchived_courses": [
            {
                "semester": "f19",
                "title": "blank",
                "display_name": "",
                "display_semester": "Fall 2019"
            }
        ],
        "archived_courses": [
            {
                "semester": "f19",
                "title": "sample",
                "display_name": "",
                "display_semester": "Fall 2019"
            }
        ]
    }
}

Get all the courses the user is taking or have taken.

HTTP Request

GET /api/courses

Create Courses

curl --request POST \
  --url <base_url>/api/courses \
  --form course_semester=f19 \
  --form course_title=api \
  --form head_instructor=instructor \
  --form base_course_semester=f19 \
  --form base_course_title=sample \
  --header 'Authorization: my_token'

This endpoint creates a course based on an existing course.

Note that the endpoint builds a course based on a prior course offering (called base course in API). Instructors and graders with access to the prior course files on GNU/Linux will be able to see the content of the new course as well. Contact the system administrator if this course should not share a GNU/Linux group with any prior course.

HTTP Request

POST /api/courses

Parameters

Parameter Description
course_semester Semester of the new course
course_title Title (or code) of the new course
head_instructor Head instructor of the new course
base_course_semester Semester of the base course
base_course_title Title (or code) of the base course

Courses.Users

Get Users

curl --request GET \
  --url <base_url>/api/<semester>/<course>/users \
  --header 'Authorization: my_token'

The above command returns JSON structured like this:

{
    "status": "success",
    "data": [
        {
            "first_name": "Alyssa P",
            "last_name": "Hacker",
            "user_id": "aphacker",
            "email": "alyssaphacker@example.com",
            "reg_section": "1",
            "rot_section": "NULL",
            "group": "Student"
        },
        {
            "first_name": "Delphia",
            "last_name": "Aufderhar",
            "user_id": "aufded",
            "email": "aufded@example.com",
            "reg_section": "1",
            "rot_section": "1",
            "group": "Student"
        },
    ]
}

This end point gets all users in a course.

HTTP Request

GET /api/<semester>/<course>/users

Get Graders

curl --request GET \
  --url <base_url>/api/<semester>/<course>/graders \
  --header 'Authorization: my_token'

The above command returns JSON structured like this:

{
    "status": "success",
    "data": [
        {
            "first_name": "Quinn",
            "last_name": "Instructor",
            "user_id": "instructor",
            "email": "instructor@example.com",
            "reg_section": "All",
            "rot_section": "NULL",
            "group": "Instructor"
        },
        {
            "first_name": "Jill",
            "last_name": "TA",
            "user_id": "ta",
            "email": "ta@example.com",
            "reg_section": "",
            "rot_section": "NULL",
            "group": "Full Access Grader (Grad TA)"
        },
    ]
}

HTTP Request

GET /api/<semester>/<course>/graders

Courses.Reports

Generate Grade Summaries

curl --request POST \
  --url <base_url>/api/<semester>/<course>/reports/summaries \
  --header 'Authorization: my_token'

This endpoint helps system administrators set up cron jobs for automatic grade summary generation.

HTTP Request

POST /api/<semester>/<course>/reports/summaries

Gradeables

Download Gradeable JSON

curl --request GET \
  --url <base_url>/api/<semester>/<course>/<gradeable_id>/download \
  --header 'Authorization: my_token'

This endpoint downloads the JSON representation of the gradeable with the given gradeable_id, course, and semester. This JSON file can be uploaded to add create a new gradeable.

HTTP Request

GET /api/<semester>/<course>/<gradeable_id>/download

Parameters

Parameter Description
semester Semester of the gradeable
course Course of the gradeable
gradeable_id ID of the gradeable

Upload Gradeable JSON

Coming Soon

Students

Get gradeable values

curl -X GET \
  <base_url>/api/<semester>/<course>/gradeable/<gradeable_id>/values?user_id=<user_id>

Possible response examples:

{
    "status": "success",
    "data": {
        "is_queued": false,
        "queue_position": 3,
        "is_grading": false,
        "has_submission": true,
        "autograding_complete": true,
        "has_active_version": true,
        "highest_version": 1,
        "total_points": 0,
        "total_percent": 0
    }
}

{
    "status": "fail",
    "message": "Gradeable does not exist"
}

The endpoint returns values associated with an autograded gradeable with the given gradeable_id, which allows for desemesterining a score on an assignment, if it has been graded, etc.

HTTP Request

GET /api/<semester>/<course>/gradeable/<gradeable_id>/values?user_id=<user_id>

Parameters

Parameter Description
user_id User's unique ID

Submit VCS Gradeable

curl -X POST \
  <base_url>/api/<semester>/<course>/gradeable/<gradeable_id>/upload\
  -F user_id=student \
  -F vcs_checkout=true \
  -F git_repo_id=true

Possible responses:

{
    "status": "success",
    "data": "Successfully uploaded version {#} for {Gradeable Title}"
}

{
    "status": "fail",
    "message": "Invalid gradeable id '{Gradeable ID}'"
}

{
    "status": "fail",
    "message": "Student API for upload only supports VCS gradeables"
}

The endpoint requests for a VCS gradeable with the given gradeable_id to be submitted.

HTTP Request

POST /api/<semester>/<course>/gradeable/<gradeable_id>/grade

Parameters

Parameter Description
user_id User's unique ID
vcs_checkout Required to be true
git_repo_id Required value, however no specific value is checked.
shell