Every request contains a number of parameters that must or can be passed. If the request
uses the GET-verb, then the mandatory arguments must be inserted into the indicated
positions in the URL:
Optional arguments should be passed through the query string:
For other methods the arguments should be passed in the request body, encoded as a JSON object.
The only exception is the token field, which should be passed through the HTTP Authorization header with type AutaToken.
Every valid response is a JSON object. An empty response carries no metadata, which means that an empty response is represented by an empty object.
Invalid requests or server-side exceptions may include one or more error messages under the
key "errors" as an array of error objects:
Some errors are common to all requests:
| Property | Type | Required | Description |
|---|---|---|---|
| username | string | yes | the user's username |
| password | string | yes | the user's password |
Requests an authentication token for an username and password. Will return an HTTP 403 with an error message if the credentials are invalid. Will return an HTTP 200 if the login succeeded.
An optional desired token lifetime can be supplied, which will be considered an upper bound (i.e., the endpoint may also return tokens with a shorter lifetime.)
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the token to invalidate |
| page | string | no | the page number to display, 1-indexed, defaults to 1 |
| pageSize | string | no | the number of users to display per page, defaults to 25 |
Returns a list of normal users.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the token to invalidate |
Invalidates a login token, effectively logging out the client. Will return an HTTP 403 if the token is not a valid token.
| Property | Type | Required | Description |
|---|---|---|---|
| username | string | yes | the user's username |
| password | string | yes | the user's password |
| authority | string | yes | the authority assigned to the user |
Creates a new user with the specified username, password and authority. The given authority decides which actions the user can perform.
Will return an HTTP 400 if the specified authority is incorrect and an HTTP 403 if the specified username already exists. Current supported authorities are: "ROLE_ADMIN", "ROLE_TEACHER", "ROLE_TA" and "ROLE_STUDENT".
| Property | Type | Required | Description |
|---|---|---|---|
| username | string | yes | the username to change the password for |
| password | string | yes | the new password for the user |
| oldPassword | string | yes | the old password of the user |
Changes the password of a user, returns an HTTP 403 if the old password is not correct for the given user.
Returns an HTTP 400 if the provided fields are of the wrong type. Returns an HTTP 403 if the provided combination of username and password is incorrect. Returns an HTTP 200 if the password change succeeded.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | no | the user's authentication token |
Verifies the validity of a token without side-effects. If the token is valid, the user's details (name, status, and granted authorities) are returned.
Returns an HTTP 401 if the user is not authenticated. Returns an HTTP 200 if the request succeeded.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
| name | string | yes | the assignment name |
| language | string | yes | the language for the assignment |
| static | list | no | the metrics for the assignment |
| dockerAuthConfigurations | list<auth configuration> | no | registry authentication details to pass to Docker |
Adds a new assignment.
Returns the id of the newly created assignment.
If no metrics are specified, no checks will be run.
Returns an HTTP 409 if the assignment already exists. Returns an HTTP 201 if the assignment was created.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
Gets a list of all assignment ids and their corresponding names.
Returns an HTTP 200 if the request succeeded.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
| id | string | yes | The id of the assignment |
| name | string | yes | The name of the assignment |
| language | string | yes | The language for the assignment |
| static | list | yes | The metrics for the assignment |
| dockerAuthConfigurations | list<auth configuration> | no | registry authentication details to pass to Docker |
Updates an assignment
Returns an HTTP 404 if the assignment could not be found. Returns an HTTP 200 if the request succeeded.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
| id | string | yes | the assignment's id |
Lists all submission IDs for a given assignment.
Returns an HTTP 404 if the assignment could not be found. Returns an HTTP 200 if the request succeeded.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
| Assignment id | string | yes | The id of the assignment |
Deletes an assignment, returns the id of the deleted assignment
Returns an HTTP 200 if the deletion succeeded. Returns an HTTP 404 if the id couldn't be found.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
| aid | string | yes | the assignment's id |
| page | integer | no | the current page of submissions, the number depends on the page size. Defaults to 1. |
| size | integer | no | the number of submissions per page. Defaults to 25, and at most 1000. |
Lists some or all submissions for an assignment. Results are paginated; the page number and size can be passed using optional query parameters. Each submission entry will contain at least the name and ID.
Returns an HTTP 200 if the deletion succeeded. Returns an HTTP 404 if the id couldn't be found.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
| aid | string | yes | the assignment id |
| name | string | yes | the name of the assignment |
Creates a new submission, returns the id of the submission.
If the name and the identity match an already existing submission, the old submission data will be deleted.
Returns an HTTP 201 if the request succeeded, returns an HTTP 404 if the assignment couldn't be found.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
Returns a new worker token, only available if user is admin
Returns an HTTP 403 forbidden if the user has not the right privileges. Returns an HTTP 400 if the request succeeded.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
| aid | string | yes | the assignment's id |
| format | string | no | the file format the export should have. Can be json or csv, any text case is accepted. Defaults to json. |
| csvformat | string | no | the CSV flavor to use for exporting. This may be any of the formats supported by Apache Commons CSV, with any text case being accepted. This parameter defaults to excel (note that the default value is not default!) If the export format is not CSV, this value is ignored. |
Exports all submissions for an assignment.
By default, both output formats have the same fields; future extensions may add request fields that add or remove fields from either format. The default fields are:
| Name | Type | Empty? | Value |
|---|---|---|---|
| assignment | string | never | the identifier of the assignment the submission was for |
| identity | string | if anonymous | the identity of the submitter, if any |
| submitted | timestamp | never | the timestamp the submission was received |
| dispatched | timestamp | if waiting for analysis | the timestamp the submission was sent to a worker for analysis |
| analyzed | timestamp | if yet to be analyzed | the timestamp the submission was completely analyzed |
| processed | timestamp | if yet to be reported on or graded | the timestamp the submission was fully processed by the system and a verdict and grade were ready |
| id | string | never | the submission's identifier |
| name | string | never | the submission's display name |
| verdict | string | if yet to be reported on or graded | the final report verdict |
| grade | number | if yet to be reported on or graded | the final grade |
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
| aid | string | yes | the assignment's id |
| iid | string | yes | the submitter's id |
| format | string | no | the file format the export should have |
| csvformat | string | no | the CSV flavor to use for exporting |
Exports all submissions for an assignment by a specific identity. This endpoint has the same contract as a full export, but only submissions by a single identity are returned.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
| iid | string | yes | the submitter's id |
| format | string | no | the file format the export should have |
| csvformat | string | no | the CSV flavor to use for exporting |
Exports all submissions for all assignments by an identity. This endpoint has the same contract as a single-assignment identity export, but all assignments were submissions are for are returned instead.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
| aid | string | yes | the assignment's id |
| sid | string | yes | the desired submissions's ID |
| format | string | no | The desired report format. Options: "html". Default is json |
Gets a submission by its ID. Returns an HTTP 404 if the assignment ID or submission ID do not exist. Returns an HTTP 200 if the request succeeded.
The report is null until it is ready. That is when the verdict is no longer pending.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
| aid | string | yes | the assignment's id |
| directUploadId | string | yes | the id used to set the name of the submission and filename |
| file | multipart/form-data | yes | the file to upload |
| identifier | string | no | the identity of the submitter |
Uploads a multipart file to be analyzed. The file must have the following format: "name":"file", "filename":[ANYTHING].[EXTENSION]. Files without a filename or extension will be rejected. Returns HTTP 201 if the file has been uploaded successfully.
Creates a submission called direct-upload:directUploadId
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
| aid | string | yes | the assignment's id |
| sid | string | yes | the desired submissions's ID |
| riskCategories | set[double] | yes | the categories used to assign metric results to a certain risk category |
| rankingTable | double[][] | yes | the table used to map the relative weight of system code in each risk category to a total system rating |
| metricNameString | string | yes | the metric name to analyze |
| entityLevelString | string | yes | the entitylevel to analyze |
Requests the benchmarking rank for a certain metric. The rank is an integer in the range 0-5.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
| aid | string | yes | the assignment id |
| sid | string | yes | the submission id |
| metricNameString | string | yes | the metric name to analyze |
| entityLevelString | string | yes | the entitylevel to analyze, options: "METHOD", "CLASS", "FILE", "MODULE", "PROJECT", "FIELD" |
Gets the benchmarking chart data.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
| aid | string | yes | the assignment's id |
| sid | string | yes | the desired submissions's ID |
| type | string | no | the type to aggregate for, options=raw, default=entity |
| metricNameString | string | yes | the metric name to analyze |
| entityLevelString | string | yes | the entitylevel to analyze |
Aggregates all metrics of a certain type into a Map of value -> total relative weights
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
| aid | string | yes | the assignment's id |
| sid | string | yes | the desired submissions's ID |
| metricNameString | string | yes | the metric name to analyze |
| entityLevelString | string | yes | the entitylevel to analyze |
Returns the benchmarking result as an HTML page.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
Requests all courses.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
| name | string | yes | the course name |
| courseCode | string | yes | the course code |
| year | int | yes | the year the course started in, >1970 |
Creates a new course.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
| cid | string | yes | the course id |
| aid | string | yes | the assignment id to add |
Adds an assignment to a course.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
| cid | string | yes | the course id |
| role | string | yes | the role that the user will have in the course (ROLE_TA or ROLE_TEACHER) |
| username | string | yes | the username to add |
Adds a user to a course with a specified role. The user must have a role of ROLE_TA or ROLE_TEACHER.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
| cid | string | yes | The course id |
Deletes a course, returns an HTTP 200 is the request succeeded. Returns an HTTP 400 if the course was not found.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
| cid | string | yes | the course id |
| name | string | yes | the course name |
| courseCode | string | yes | the course code |
| year | int | yes | the year the course started in, >1970 |
Updates a course.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
| cid | string | yes | the course id |
Retrieves a course.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
| cid | string | yes | the course id |
| role | string | yes | the role of the user that will be removed, should be ROLE_TA or ROLE_TEACHER |
| username | string | yes | the username |
Removes a user from a course.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
| cid | string | yes | the course id |
| aid | string | yes | the assignment id |
Removes an assignment from a course.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
| path | string | yes | relative path to the a directory or file to be inspected |
Inspect a file or folder to get information about modification date, name and size. Also includes the contents of a directory.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
| path | string | yes | relative path to the a directory or file to be retrieved |
Gets a file from the server. Returns the file as an octet-stream.
If the requested file is not a file.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
| path | string | yes | relative path to the a directory or file to be created |
| file | multipart file | yes | the file to be uploaded |
Uploads a multipart file to the server at a specified path.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
Gets a list of languages and the metrics supported for that language.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
Gets a map of all languages and their metrics.
Deprecated - originally a hack for the old UI to allow this resource to load in a blocking fashion, no longer necessary
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
Returns a map containing test fixtures for criteria scripts.
It is important to note that the fixtures can be of any type, as long as the type is valid for the metric it belongs to.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
| script | string | yes | the script to test |
| tests | list<spec> | yes | the tests to run |
A unit test specification ("spec") is an object containing an identifier id for the test and a value value to pass to the script under test.
Validates a passing script.
The script is checked whether it compiles (mostly for syntax errors) and is then run against the provided values. The results are returned, along with any errors generated when running the test, as if the script were run on an entity.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
Gets a list of all workers connected to the core.
Each worker is represented by a description containing a name, hostname, load, and the instant the last ping was received. If the worker was busy at the moment of the request, a job description consisting of an assignment and submission ID is included.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
Gets a list of the current global settings of the core and the workers.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
| settings | map | yes | the updated settings |
Uploads the updated settings file to the server at a specified path.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token | aid | string | yes | the assignment's id |
| file | multipart file | yes | the file to be uploaded |
| filename | string | yes | the name of the file |
| projectName | string | yes | the name of the cpm project |
| workunitID | string | yes | the id of the cpm workunit |
| workunitName | string | yes | The name of the cpm workunit |
| memberName | string | yes | the name of the cpm member |
| uploadComments | string | no | the comments for the cpm submission |
| verificationCode | string | yes | The cpm verification code |
Submits a new submission to be checked, using a file from the cpm submission.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
Gets the latest entries in the core's log. Up to 1024 entries are retained.
| Property | Type | Required | Description |
|---|---|---|---|
| token | string | yes | the user's authentication token |
| aid | string | yes | the assignment id |
| sid | string | yes | the submission id |
Retrieves the verdict for a submission