Skip to content
This repository has been archived by the owner on Nov 11, 2019. It is now read-only.

Endpoints

Jump to bottom
Ayush Ranjan edited this page May 26, 2019 · 12 revisions

Authentication

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.

Response Format

All API responses have the following format:

{
    "data": <body dict specified in the endpoint docs below>,
    "status": <string describing the status of this request>
}

Client Endpoints

These are the endpoints used by registered courses.

Grading Config

Used to add or get the grading config for an assignment under a particular course.

Endpoint - /api/v1/grading_config/[course_id]/[assignment_name]

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.

Grading Run

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]

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>
}

Grading Run Status

Used to get the grading run status

Endpoint - /api/v1/grading_run_status/[course_id]/[run_id]

URI Parameters:

  • course_id- unique identifier for a course
  • run_id - unique identifier for the 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>, ...
     }
}

Grading Job Log

Used to get grading job logs.

Endpoint - /api/v1/grading_job_log/[course_id]/[job_id]

URI Parameters:

  • course_id- the unique identifier for a course
  • job_id - the unique identifier for the 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>
}

Course Worker Status

Used to assess system health.

Endpoint - /api/v1/worker/[course_id]/[scope]

URI Parameters:

  • course_id- the 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). Can be used to get an overview of the system 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>
             }, ...
       ]
}
Clone this wiki locally