API docs by Redocly

eTutor Task-App API Contract (1.1.1)

Download OpenAPI specification:Download

This document describes the RESTful API that eTutor Task apps must comply with in order for task creation to work with eTutor Task-Administration. Task apps may have additional endpoints that can be called by the task administration UI. The task administration server will forward the requests from the UI to the task app.

Authentication is performed using API keys. Different API keys may have different roles:

  • CRUD: Create, read, update, and delete tasks and task groups.
  • SUBMIT: Submit submissions
  • READ_SUBMISSION: Read persisted submissions

TaskGroup

Manage task groups

Get task group

Returns the task group type specific data of the requested task group. This is used by the task administration to retrieve the form values for editing the task group. Requires the CRUD role.

Authorizations:
api_key
path Parameters
id
required
integer <int64>

The task group identifier.

Responses

Response samples

Content type
application/json
{
  • "ddl": "CREATE TABLE test (id INTEGER);"
}

Create task group

Creates a new task group. The new task group is stored under the specified identifier. Requires the CRUD role.

Authorizations:
api_key
path Parameters
id
required
integer <int64>

The task group identifier.

Request Body schema: application/json
required

Task group data

taskGroupType
required
string [ 2 .. 100 ] characters

The task group type. If a task app supports more than one task group type, this can be used to distinguish between types.

status
required
string
Enum: "DRAFT" "READY_FOR_APPROVAL" "APPROVED"

The task group status.

required
object

The task group type specific data. The content of this object depends on the task group type.

Responses

Request samples

Content type
application/json
{
  • "taskGroupType": "sql",
  • "status": "DRAFT",
  • "additionalData": {
    }
}

Response samples

Content type
application/json
{
  • "descriptionDe": "Gesucht ist eine Zahl zwischen 1 und 10.",
  • "descriptionEn": "We are looking for a number between 1 and 10."
}

Modify task group

Updates an existing task group. Requires the CRUD role.

Authorizations:
api_key
path Parameters
id
required
integer <int64>

The task group identifier.

Request Body schema: application/json
required

Task group data

taskGroupType
required
string [ 2 .. 100 ] characters

The task group type. If a task app supports more than one task group type, this can be used to distinguish between types.

status
required
string
Enum: "DRAFT" "READY_FOR_APPROVAL" "APPROVED"

The task group status.

required
object

The task group type specific data. The content of this object depends on the task group type.

Responses

Request samples

Content type
application/json
{
  • "taskGroupType": "sql",
  • "status": "DRAFT",
  • "additionalData": {
    }
}

Response samples

Content type
application/json
{
  • "descriptionDe": "Gesucht ist eine Zahl zwischen 1 und 10.",
  • "descriptionEn": "We are looking for a number between 1 and 10."
}

Delete task group

Deletes an existing task group. Does not return an error if the specified task group does not exist. Requires the CRUD role.

Authorizations:
api_key
path Parameters
id
required
integer <int64>

The task group identifier.

Responses

Task

Manage tasks

Get task

Returns the task type specific data of the requested task. This is used by the task administration to retrieve the form values for editing the task. Requires the CRUD role.

Authorizations:
api_key
path Parameters
id
required
integer <int64>

The task identifier.

Responses

Response samples

Content type
application/json
{
  • "solution": "SELECT id FROM student;"
}

Create task

Creates a new task. The new task is stored under the specified identifier. Requires the CRUD role.

Authorizations:
api_key
path Parameters
id
required
integer <int64>

The task identifier.

Request Body schema: application/json
required

Task data

taskGroupId
integer <int64>

The task group identifier, if applicable.

maxPoints
required
number

The maximum achievable points.

taskType
required
string [ 2 .. 100 ] characters

The task type. If a task app supports more than one task type, this can be used to distinguish between types.

status
required
string
Enum: "DRAFT" "READY_FOR_APPROVAL" "APPROVED"

The task status.

required
object

The task type specific data. The content of this object depends on the task type.

Responses

Request samples

Content type
application/json
{
  • "taskGroupId": 445,
  • "maxPoints": 10.5,
  • "taskType": "sql",
  • "status": "DRAFT",
  • "additionalData": {
    }
}

Response samples

Content type
application/json
{
  • "descriptionDe": "Geben Sie eine Zahl ein.",
  • "descriptionEn": "Enter a number.",
  • "difficulty": 2,
  • "maxPoints": 25.75
}

Modify task

Updates an existing task. Requires the CRUD role.

Authorizations:
api_key
path Parameters
id
required
integer <int64>

The task identifier.

Request Body schema: application/json
required

Task data

taskGroupId
integer <int64>

The task group identifier, if applicable.

maxPoints
required
number

The maximum achievable points.

taskType
required
string [ 2 .. 100 ] characters

The task type. If a task app supports more than one task type, this can be used to distinguish between types.

status
required
string
Enum: "DRAFT" "READY_FOR_APPROVAL" "APPROVED"

The task status.

required
object

The task type specific data. The content of this object depends on the task type.

Responses

Request samples

Content type
application/json
{
  • "taskGroupId": 445,
  • "maxPoints": 10.5,
  • "taskType": "sql",
  • "status": "DRAFT",
  • "additionalData": {
    }
}

Response samples

Content type
application/json
{
  • "descriptionDe": "Geben Sie eine Zahl ein.",
  • "descriptionEn": "Enter a number.",
  • "difficulty": 2,
  • "maxPoints": 25.75
}

Delete task

Deletes an existing task. Does not return an error if the specified task does not exist. Requires the CRUD role.

Authorizations:
api_key
path Parameters
id
required
integer <int64>

The task identifier.

Responses

Submission

Manage submissions

Get submissions

Returns a paged and filtered list of submissions. Requires the READ_SUBMISSION role.

Authorizations:
api_key
query Parameters
page
integer >= 0
Default: 0

Zero-based page index (0..N)

size
integer >= 1
Default: 20

The size of the page to be returned

sort
Array of strings

Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.

userFilter
string
Default: null
Example: userFilter=k1234567

User filter string (applies equals to userId).

taskFilter
integer <int64>
Default: null
Example: taskFilter=109

Task filter string (applies equals to taskId).

assignmentFilter
string
Default: null
Example: assignmentFilter=moodle_quiz_10

Assignment filter string (applies equals to assignmentId).

modeFilter
string
Enum: "RUN" "DIAGNOSE" "SUBMIT"

Submission mode filter string (applies equals to mode).

Responses

Response samples

Content type
application/json
{
  • "totalElements": 35,
  • "totalPages": 4,
  • "size": 10,
  • "number": 3,
  • "numberOfElements": 5,
  • "content": [
    ]
}

Execute and grade submission

Executes and grades a submission. If runInBackground is true, only the submission identifier will be returned; otherwise the evaluation result will be returned. Requires the SUBMIT role.

Authorizations:
api_key
query Parameters
runInBackground
boolean
Default: false

Whether to run the grading in background or wait for grading to finish.

persist
boolean
Default: true

Whether to persist the submission. Only applies if runInBackground is false.

Request Body schema: application/json
required

The submission data.

userId
string [ 0 .. 255 ] characters

The user identifier (can be used e.g. for plagiarism check).

assignmentId
string [ 0 .. 255 ] characters

The assignment identifier (can be used e.g. for plagiarism check).

taskId
required
integer <int64>

The task identifier.

language
required
string = 2 characters de|en

The user interface language. The feedback should be returned in the requested language.

mode
required
string
Enum: "RUN" "DIAGNOSE" "SUBMIT"

The submission mode. Might be expanded in future releases.

feedbackLevel
required
integer <int32> [ 0 .. 3 ]

The feedback level.

required
object

The submission of the user. If the submission consists only of a string, then this object should contain a single property with the key input and the value of the submission as the property value. This ensures it can easily be tested in Task administration UI.

Responses

Request samples

Content type
application/json
{
  • "userId": "k12212345",
  • "assignmentId": "moodle_quiz_3",
  • "taskId": 8911,
  • "language": "st",
  • "mode": "RUN",
  • "feedbackLevel": 3,
  • "submission": {
    }
}

Response samples

Content type
application/json
{
  • "submissionId": "23243110-f447-42f4-a433-27cb8d276b19",
  • "grading": {
    }
}

Get evaluation result

Returns the evaluation result for the requested submission. Waits for the specified timeout for the result to be available. Requires the SUBMIT role.

path Parameters
id
required
string <uuid>

The submission identifier.

query Parameters
delete
boolean
Default: false

Whether to delete the submission after retrieval.

header Parameters
X-API-TIMEOUT
integer <int32>
Default: 10

The maximum amount of seconds to wait for the result.

Responses

Response samples

Content type
application/json
{
  • "maxPoints": 10.5,
  • "points": 7.5,
  • "generalFeedback": "<p>Your solution is correct.</p>",
  • "criteria": [
    ]
}

Health

Monitor application health

Provide application logfile

Returns the application logfile. Requires the CRUD role. This is an optional endpoint.

Responses

Provide application information.

Returns some information about the application. Requires the CRUD role. This is an optional endpoint.

Responses

Response samples

Content type
application/json
{
  • "git": {
    },
  • "build": {
    },
  • "os": {
    }
}

Provides application health information

Returns the health information of the application. This is a required endpoint. If not authenticated, the server should only return the "status"-property. If authenticated, the server may also return health details of the components.

Responses

Response samples

Content type
application/json
{
  • "status": "UP",
  • "components": {
    }
}