-
Notifications
You must be signed in to change notification settings - Fork 0
Endpoints
The headers of all the requests need to have the token authentication format as specified by HTTP Authentication scheme. The format is:
{
"Authorization": "Bearer <token>"
}
Courses need to use the tokens they specified for themselves to the admin. Worker nodes need to use the cluster token.
All API responses have the following format:
{
"data": <body dict specified in the endpoint docs below>,
"status": <string describing the status of this request>
}
These are the endpoints used by registered courses.
Used to add or get the grading config for an assignment under a particular course.
Endpoint - /api/v1/grading_config/[course_id]/[assignment_name]
Tokens allowed: admin only
URI Parameters:
-
course_id- unique identifier for a course -
assignment_name- unique identifier for an assignment within a course
GET - Returns the grading config if it exists. The response body will have the exact same config that was uploaded.
POST - Body should be the grading config. Saves the assignment config under the given course and assignment name.
Used to start an autograder run for an assignment. Schedules all the grading jobs in the correct order. The preprocessing job is run first if it exists. Once that is successful, the student grading jobs are scheduled and executed parallelly across multiple graders. Once all the student grading jobs have finished executing (succeeded or failed), the post-processing job will be scheduled.
Endpoint - /api/v1/grading_run/[course_id]/[assignment_name]
Tokens allowed: admin only
URI Parameters:
-
course_id- unique identifier for a course -
assignment_name- unique identifier for an assignment within a course
POST - Body should be the run-time environment variables config. This will determine the number of student grading jobs.
Response Format:
{
"grading_run_id": <unique grading run id>
}
Used to get the grading run status
Endpoint - /api/v1/grading_run_status/[course_id]/[run_id]
Tokens allowed: admin or query
URI Parameters:
-
course_id- unique identifier for a course -
run_id- unique identifier for a grading run
GET - Shows the state of all the grading jobs under this grading request. The response contains job-id to state mappings. These job ids are important to get the logs for that job. Hence this endpoint can also be used to get all the job ids.
The grading job state is a string which will represent one of the following states:
- QUEUED - the grading job has been added to the run queue
- STARTED - the grading job has been polled by a worker node and is being currently run
- FAILED - the worker node was unsuccessful in running the chain of container specified
- SUCCEEDED - the worker node successfully ran all the specified containers
The grading run state is a string which will represent one of the following states:
- READY - grading run is ready to be started
- PRE_PROCESSING_STAGE - the pre-processing job has been scheduled and is potentially running
- STUDENTS_STAGE - the students grading jobs have been scheduled and are running (implies that if there was a pre-processing job, it was successful)
- POST_PROCESSING_STAGE - the post-processing job has been scheduled and is potentially running
- FINISHED - Grading run is complete. pre/post-processing jobs (if they existed) were successful. All grading jobs have finished executing.
- FAILED - Grading run failed. Either pre/post-processing jobs failed.
Response Format:
{
"state": <grading run state>
"pre_processing_job": {<pre-processing-job-id>: <grading job state>},
"post_processing_job": {<post-processing-job-id>: <grading job state>},
"student_jobs": {
<job-id>: <grading job state>, ...
}
}
Used to get the grading run environment variable
Endpoint - /api/v1/grading_run_env/[course_id]/[run_id]
Tokens allowed: admin only
URI Parameters:
-
course_id- unique identifier for a course -
run_id- unique identifier for a grading run
GET - Shows the environments for each grading job within the specifies grading run. The response consists of job-id to env mappings, and each environment is itself a mapping between env-variable's and a list of env-value's. We use a list because each job has multiple stages, so we retain the env-value's from every stage if they are different.
Response Format:
{
"pre_processing_env": {<pre-processing-job-id>: {<env-variable>: [<env-value>, ...]}},
"post_processing_env": {<post-processing-job-id>: {<env-variable>: [<env-value>, ...]}},
"student_env": {
<job-id>: {<env-variable>: [<env-value>, ...]}, ...
}
}
Used to get grading job logs.
Endpoint - /api/v1/grading_job_log/[course_id]/[job_id]
Tokens allowed: admin only
URI Parameters:
-
course_id- unique identifier for a course -
job_id- unique identifier for a grading job
GET - Used to get grading job logs. This will be the stdout and stderr from all the containers which were run. This is meant to be used for debugging purposes.
Response Format:
{
"stdout": <concatenation of all stdout output from the sequence of containers>,
"stderr": <concatenation of all stderr output from the sequence of containers>
}
Used to assess system health.
Endpoint - /api/v1/worker/[course_id]/[scope]
Tokens allowed: admin only
URI Parameters:
-
course_id- unique identifier for a course -
scope- the filter applied to the response.
| Scope | Description |
|---|---|
| all | Returns all the worker nodes available for this course. |
GET - Shows the worker nodes available for a specific course filtered by the scope the user wants. This endpoint shows the worker node status (alive/dead, busy/available, number of jobs processes, hostname). It can be used to get an overview of the system's health. Currently, all worker nodes are available to all courses but later we can have a quota or some policy as to how much of the grading cluster a course has access to.
Response Format:
{
"worker_nodes": [
{
"hostname": <hostname of the machine on which the grader is running>,
"jobs_processed": <number of jobs processed since joining the cluster>,
"busy": <True/False>,
"alive": <True/False>
}, ...
]
}
Used to determine how many grading jobs are queued for a given course.
Endpoint - /api/v1/queue/[course_id]/length
Tokens allowed: admin only
URI Parameters:
-
course_id- unique identifier for a course
GET - Used to get the length of a course's grading job queue.
Response Format:
{
"length": <queue length>
}
Used to determine how many grading jobs are in front of a given job within its course's queue.
Endpoint - /api/v1/queue/[course_id]/[job_id]/position
Tokens allowed: admin or query
URI Parameters:
-
course_id- unique identifier for a course -
job_id- unique identifier for a grading job
GET - Used to get how many grading jobs are in front of a given job. For example, if 0 is returned, the given job is at the front of the course's queue.
Response Format:
{
"position": <queue position>
}
Subscribe to server-sent events regarding the progress of a grading job.
Endpoint - /api/v1/stream/[course_id]/[job_id]
Tokens allowed: admin or query
URI Parameters:
-
course_id- unique identifier for a course -
job_id- unique identifier for a grading job
GET - Receive events from the server about the selected job.
SSE event name - status_update
Response format:
event: status_update\ndata: [JSON_BLOB]\n\n
Example response:
event: status_update\ndata: {"type": "state", "data": "STARTED"}\n\n
JSON blob format:
{
"type": [update type],
"data": [relevant data]
}
| Update Type | Data Value | Description |
|---|---|---|
"state" |
"STARTED" |
Sent when a job is pulled from the queue and started |
"state" |
"FINISHED" |
Sent when a job successfully finishes |
"state" |
"FAILED" |
Sent when a job fails |
"position" |
A non-negative integer | The job's new position in the queue. Sent when a job is pulled from the queue. |