vmchecker web services

The communication between client UI and vmchecker server will be performed using REST-RPC requests. The content of the data exchanged will be encoded in JSON format.

The following services will be available:

Authentication process

Authentication will be implemented by using session variables (either in php or python), and the session id exchanging will be performed transparently to the UI application, by using standard headers. So any other call made later to the services won’t need data like username, since all request will be associated with an unique user, and any data about him can be deducted on the server counterpart.
Using session variables taints a little the REST service-oriented architecture, but for now it should be fine.

login

Method: POST

Parameters:

• username
• password

Result: an AuthenticationResponse object, with the following fields:

• status: boolean indicating that authentication process failed or not
• username: recorded username – it can be different from the sent credential and it will be used for display in the right corner of the header
• info: useful for changing reasons of failure

logout

Will destroy the session variable and the cookie associated within the browser.

Method: POST

Parameters: None

Result: None

Data retrieval

All of the following request should be allowed only for authenticated users, so all of them should be implemented with a layer of authentication checking that basically checks the session variable associated with the sender. Notice that this session id will be automatically sent through a cookie, so additional data parameters are not required.

getCourses

method: GET

Paramaters: None

Result: An object will the following fields:

• id: course id, a text without spaces or other URL non-friendly characters. Examples: pso, so, cpl
• title: course title. Example: ‘Sisteme de Operare’

getAssignments

method:GET

Parameters:

• courseId

Result: Array of assignment objects. An assignment object contains the following fields:

• assignmentId: a key for the assignment. Example: ‘tema1-lin’
• assignmentTitle
• deadline

uploadAssignment

method: POST

Parameters:

• courseId
• assignmentId
• archiveFile

Result:

• status: a boolean value
• dumpLog: a text log with additional information

getResults

method: GET

Parameters:

• courseId
• assignmentId

Result:

• an array with all the result files relevant to the student. An entry in this array is a dictionary of the form “file name” : “file contents”. The names of the files are descriptions like “The stdout of the build process”, or “Grade and comments”. The contents of the files do not contain HTML markup and are preformatted using whitespace and newlines.

getAllResults

method: GET

Parameters:

• courseId

Result:

• an array with one entry for each student. An entry is represented by an object with the following fields:
  • studentName: string
  • studentId: string
  • results: object with fields for each assignment {"assignmentId1": “results1”, “assignmentId2”: “results2”, …}.

Error handling and reporting

Any error/exception that occurs during the execution of a remote procedure call should end in a special error message encoded also in JSON, with the following fields:

• errorType: the type of the error, which is a numeric value. For example: ERR_AUTH = 1, ERR_EXCEPTION = 2, ERR_OTHER = 3. These types must be defined consistent in both server side and client side components.
• errorMessage: the title of the error/exception, which must be short and suggestive
• errorTrace: this field is strongly related with exceptions, but not restricted to these. It should contain all the stack trace dump for an exception which will ease tracing and fixing problems in vmchecker.