Web Service - Overview

This page details the subset of the web service API that exposes functionality for your application’s backend.

URL Description
/session/create Create a new interaction from an Exercise Definition or from the ID of a predefined exercise in the CMS.
/session/retrieve Create a new interaction from an Exercise Definition or from the ID of a predefined exercise in the CMS.
/session/solution Get the worked-out solution for an exercise or for an existing session.
/session/results Returns information contained in the session, such as scoring and the students‘ actions (incl. evaluation results).
/session/score Calculate scoring for a session.
/exercise/generate Generate non-random instances for a randomised exercise.
/exercise/published-info Get general information of an exercise in AlgebraKiT’s CMS, such as name, interaction type and the number of difficulty levels.

Calls are made through HTTP POST to https://algebrakit.eu, where parameters are supplied as a JSON object in the message body.

Authentication

Every request must include an x-api-key header containing a unique API key that is associated with your account. You can sign up for an account here.


Create session

Create new sessions for the (possibly randomised) exercises from AlgebraKiT’s CMS. To save round trips to AlgebraKiT’s web service, you can create multiple sessions in one call. For each session, a unique session id is returned. The reply also contains the optimised html code to create and initialise the web component for each session. You can insert this html in your web page at the appropriate location.

Endpoint: /session/create

Request Body

{
   snapshotId?: <string> 
   scoringModel?: <string> 
   exercises: [{
      exerciseId?: <string>
      version?: <string>
      exerciseSpec?: {...}
      level?: <int>
      nr?: <int>
   }]
   attributes: [{key: value}]
}
Property Description
exerciseId ID of the exercise in the CMS. Either exerciseId or exerciseSpec is required.
snapshotId A snapshot contains a collection of published exercises, defined in AlgebraKiT's CMS. Either snapshotId or version is required if exerciseId is given.
version The published version number of the exercise (number) or 'latest' to indicate the current version in the CMS. Either snapshotId or version is required if exerciseId is given.
exerciseSpec Exercise Definition of the exercise. Either exerciseId or exerciseSpec is required.
scoringModel Optional. Reference to a predefined scoring model that is to be applied for the exercise and all interactions in it. If given, AlgebraKiT calculates the total marks and the marks earned, based on the evaluations of the student's input and taking into account errors and hint requests. Use 'standard' for a default scoring model. See scoring for more information.
level Optional. Difficulty level for the exercise. Applicable for randomised exercise arrangements, which generally offer multiple levels of difficulty. Default value is 0, which represents the lowest level. The number of levels of difficulty offered by the exercise, can be retrieved from /exercise-info.
nr Optional. Number of sessions to generate for this exercise. Only relevant for randomised exercises. Default value is 1.
attributes Optional. List of key-value pairs to influence the web component (see attributes ).

Output

For each element of input array exercises, an array of length nr with session results.

[{
   success: <boolean>
   msg?: <string>
   sessions: [{
     success: <boolean>
     msg?: <string>
     sessionId: <string>
     appId: <string>
     html: <string>
   }]
}]
Property Description
success Indicates if creation of the session succeeded
msg If creation of the session was not successful, information about the error.
sessionId A unique id for this session.
html Optimised html code to create the appropriate web component. For optimal performance, this html code contains already the initialization data that the web component requires.

Retrieve session

Returns the same session information that was returned by /session/create, without creating a new session. This endpoint can be useful to restore a webpage with AlgebraKiT exercises, including a student's previous input.

Endpoint: /session/retrieve

Request Body

See /session/create.


Generate exercise

Generate nonrandom Exercise Definitions from randomised exercises. With these Exercise Definitions you can repeatedly create new sessions using endpoint /session/create. A use case is to let an author define a test from a generated list of exercises. The Exercise Definitions of the chosen exercises can then be stored and used repeatedly.

To save round trips to AlgebraKiT’s web service, you can create multiple instances for multiple randomised exercises in one call.

Endpoint: /session/generate

Request body

{
   snapshotId?: <string> 
   exercises: [{
      exerciseId?: <string>
      version?: <string>
      exerciseSpec?: {...}
      level?: <int>
      nr?: <int>
   }]
   attributes: [{key: value}]
}
Property Description
exerciseId ID of the exercise in the CMS. Either exerciseId or exerciseSpec is required.
snapshotId A snapshot contains a collection of published exercises, defined in AlgebraKiT's CMS. Either snapshot or version is required if exerciseId is given.
version The published version number of the exercise (number) or 'latest' to indicate the current version in the CMS. Either snapshot or version is required if exerciseId is given.
exerciseSpec Exercise Definition of the exercise. Either exerciseId or exerciseSpec is required.
level Optional. Difficulty level for the exercise. Applicable for randomised exercise arrangements, which generally offer multiple levels of difficulty. Default value is 0, which represents the lowest level. The number of levels of difficulty offered by the exercise, can be retrieved from /exercise-info.
nr Optional. Number of sessions to generate for this exercise. Only relevant for randomised exercises. Default value is 1.
attributes Optional. List of key-value pairs to influence the web component (see attributes ).

Output

For each element of input array exercises, an array of length nr with generated exercises.

[{
   success: <boolean>
   msg?: <string>
   instances: [{
     success: <boolean>
     msg?: <string>
     exerciseSpec: <ExerciseDefinition>
     view: <ExerciseView>
   }]
}]
Property Description
success Indicates if generating the nonrandom exercise succeeded.
msg If generating the nonrandom exercise was not successful, information about the error.
view Information relevant for display in the front end, such as instruction text, assignment expression and required buttons for the formula editor.
exerciseSpec The generated Exercise Definition object.

Get solution

Get the worked-out solutions for the given sessions. The reply also contains the optimised html code to create and initialise the correct web component for this exercise. You can insert this html in your web page at the appropriate location.

Endpoint: /session/solution

Request body

{
   ids: [<string>]
}
Property Description
ids Session IDs of the desired sessions.

Output

For each session the following results.

[{
   success: <boolean>
   msg?: <string>
   sessionId: <string>
   appId: <string>
   type: <string>
   html: <string>
   }]
}]
Property Description
success Indicates if creation of the solution for this session succeeded.
msg If creation of the solution was not successful, information about the error.
sessionId The session ID of the session for which this solution was generated.
appId The app ID of the session for which this solution was generated.
html Optimised html code to create the appropriate web component. For optimal performance, this html code contains already the initialization data that the web component requires.

Get score

Perform a final evaluation of all interactions in this exercise and retrieve the session results. The input and output is the same as for Get results. The difference with this call is that a final evaluation is done before the scoring is calculated. This is required only if intermediate evaluations were disabled during student interaction.

Endpoint: /session/score


Get results

Retrieve all student actions for the given session, including evaluation results. You can use this information for example to calculate a score for the student, based on your own scoring scheme.

Endpoint: /session/result

Request Body

{
   sessionId: <string>
}
Property Description
sessionId ID of the session.

Output

An exercise can consist of multiple questions (like question a, b, c, etc), where each question can contain multiple interactions.

{
    scoring: <ScoringResult>
    questions: [{
      id: <string>
      scoring: <ScoringResult>
      interactions: <InteractionResult>[]
   }]
}
<InteractionResult> = {
   id: <string>
   type: <string>
   progress: float
   events: <EventData>[]
   scoring: <ScoringResult>
}

<EventData> =
    {
      event = 'EVALUATE'
      timestamp: long
      progress: float 
      feedback?: {
        tag: <string>
        description: <ContentElement>[]
      }
      exerciseStatus: <Status>
      inputStatus: <Status> 
    }
 |  {
      event = 'HINT'
      timestamp: long
    }

<ScoringResult> =
    {
        marksTotal: float
        marksEarned: float
        penalties: {
            hintsRequested: int
            mathErrors: int
            notationErrors: int
        }
    }

<Status> = 
   'FINISHED' | 'CORRECT' | 'ERROR' | 'NO_MATCH' | 
   'PARSE_ERROR' | 'TRUE_EXPRESSION' | 'FALSE_EXPRESSION'

The results for a single interaction contain the following properties:

Property Description
events An array containing information for every evaluation or hint.
scoring Only present if a scoring model is defined in Create Session. Contains the calculated marking for this interaction, based on the evaluations and hints.
progress Indication of what percentage of the exercise was completed.

The results for an evaluation event are:

Property Description
exerciseStatus Overall status of the exercise: FINISHED if the question is completed, CORRECT if the question is not yet completed.
inputStatus Evaluation class of the student input. See the table below for more information
progress Indication of what percentage of the exercise was completed.
feedback Applies if inputStatus='ERROR'. Contains a tag that identifies the type of mistake, such as AddDecimalsST0 for a mistake involving the addition of negative decimals.
The description consists of text and math elements and can be transformed into html for display using the frontend call AlgebraKIT.elements2html().

The property inputStatus can have the following values:

Value Description
FINISHED The input is accepted as the final answer to the question.
CORRECT The input is a correct intermediate step, but the question is not yet finished.
ERROR The input is incorrect and AlgebraKiT has diagnosed an error.
NO_MATCH AlgebraKiT was not able to relate the input to any solution step for this question. The input is probably false.
PARSE_ERROR The input is not a valid mathematical expression.
TRUE_EXPRESSION The input is a correct expression, such as 2x+3x=5x, but AlgebraKiT was not able to relate the input to any solution step for this question. The student probably made some low-levelintermediate step.
FALSE_EXPRESSION The input is incorrect, such as 2+3=6.

Exercise info

Retrieve information about an exercise in AlgebraKiT's CMS, such as available versions, the structure and the change history.

Endpoint: /exercise/published-info

Request Body

{
   id: <string>
}
Property Description
id ID of the exercise.

Output

Information about the structure of the exerc

{
    commitHistory: CommitData[];
    id: string;
    endpoint: string;
    publishedVersions: <PubVersionInfo>[];
    courseName: string;
    type: string;
}

<PubVersionInfo> = {
    name: string;
    majorVersion: number | 'latest';
    minorVersion: number;
    metadata: {[key: string]: string};
    numberOfLevels?: number;
    interactions: <InteractionInfo>[];
    resources: <ResourceInfo>[];
}

<InteractionInfo> = {
    block: string;
    refId: string;
    type: string;
    refName: string
}

<ResourceInfo> = {
    refId: string;
    type: string;
    refName: string
}