Web Service - Overview

This page describes Algebrakit's web service API.

You call the API through JSON POST, encoding parameters as a JSON object in the message body. Choose the endpoint closest to your location:

  • Ireland: https://api.algebrakit.com
  • Singapore: https://prod.api.sg-1.algebrakit.com

Note: Make sure you use the same location to load the frontend.

Every request must include an X-API-KEY header containing the unique API key associated with your account.

URL Description
/session/create Create a new interaction from an Exercise Definition or the ID of a predefined exercise in the CMS.
/session/retrieve Create a new interaction from an Exercise Definition or the ID of a predefined exercise in the CMS.
/session/solution Get the worked solution for an exercise or 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.
/sessions/lock Lock or unlock sessions for student input.
/exercise/generate Generate non-random instances for a randomised exercise.
/exercise/published-info Get general information about an exercise in Algebrakit’s CMS, such as name, interaction type, and the number of difficulty levels.
/exercise/validate Retrieve information about an exercise and perform some validation.

Create session

Create new sessions for the (possibly randomized) Algebrakit exercises. You can create multiple sessions in one call to save round trips to Algebrakit’s web service. The response contains a unique session ID for each session. The reply also contains the optimized HTML code to create and initialize the web component for each session. You can insert this HTML in your web page at the appropriate location.

Endpoint: /session/create

Request Body

{
   exercises: [{
      exerciseId?: <string>
      version?: <string>
      exerciseSpec?: <Exercise>
      sessionId?: <string>
      level?: <int>
      nr?: <int>
   }]
   scoringModel?: <string> 
   assessmentMode?: <boolean>
   requireLockForSolution?: <boolean>
   apiVersion: 2
}
Property Description
exerciseId ID of the exercise in the CMS. Either exerciseId, exerciseSpec, or sessionId is required.
version The published version number of the exercise (number) or 'latest' (default), indicating the current version in the CMS.
exerciseSpec Exercise Definition of the exercise. Either exerciseId, exerciseSpec, or sessionId is required.
sessionId ID of an existing exercise session. Except for random exercises, the behavior is the same as for exerciseId. Using exerciseId on random exercises generates a new random instance of the exercise. Using sessionId generates a new session for the same random exercise. Either exerciseId, exerciseSpec, or sessionId is required
level Optional. Difficulty level for the exercise. Applicable for randomized exercise arrangements, which generally offer multiple levels of difficulty. The default value is 0, which represents the lowest level. You can get the number of difficulty levels in the exercise from /exercise-info.
nr Optional. Number of sessions to generate for this exercise. Only relevant for randomized exercises. The default value is 1.
scoringModel Optional. Reference to a predefined scoring model for the exercise. 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. Algebrakit will use a standard scoring model that awards one mark to each interaction if omitted. See scoring for more information.
requireLockForSolution Optional. If true (default), prevents anyone from obtaining the solution to this exercise before the session is locked.
assessmentMode Optional. Setting this option to true turns off the step-by-step evaluation, hints, and feedback for the student.
apiVersion Required. Always 2.

Output

The response contains the following session results for each element of the input array exercises.

[{
   success: <boolean>
   msg?: <string>
   sessions: [{
     success: <boolean>
     msg?: <string>
     sessionId: <string>
     html: <string>
     marksTotal: <number>
     type: 'SINGLE' | 'COMPOUND'
     interactions: {id => <InteractionDescription>}
   }]
}]

InteractionDescription = {
   type: <string>
   marks: <number>
   scorable?: <boolean>
}
Property Description
success Indicates if creating of the session succeeded
msg If creating the session was unsuccessful, information about the error.
sessionId A unique ID for this session.
html Optimized html code to create the appropriate web component. This html code already contains the initialization data required by the web component for optimal performance.
type COMPOUND if the exercise has multiple questions (a, b, c, etc). Otherwise SINGLE.
marksTotal The total number of marks that can be earned with this exercise.
interactions Information about each interaction.

Retrieve session

Returns the same session information produced by /session/create without creating a new session. This endpoint can be helpful to efficiently restore a webpage with existing Algebrakit exercises, including a student's previous input.

Note that restoring an existing exercise can be done without using this endpoint, simply by the akit-exercise or akit-interaction web components:

  <akit-exercise session-id="..."></akit-exercise>

The web component will retrieve all needed information (question type, learning events, etc) from the server. However, this roundtrip impacts page load time, especially if multiple exercises are on the page. The /session/retrieve endpoint lets you obtain optimized HTML code for multiple sessions in one call. Inserting this optimized HTML into the webpage prevents a server roundtrip per exercise and allows the exercises to show instantly.

Endpoint: /session/retrieve

Request Body

{
   sessionIds: <string>[]
}
Property Description
sessionIds Array of session IDs to retrieve.

Output

See /session/create.


Generate exercise

Generate nonrandom Exercise Definitions from randomized 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 randomized exercises in one call.

Endpoint: /exercise/generate

Request body

{
   exercises: [{
      exerciseId?: <string>
      version?: <string>
      exerciseSpec?: <Exercise>
      level?: <int>
      nr?: <int>
   }]
   apiVersion: 2
}
Property Description
exerciseId ID of the exercise in the CMS. Either exerciseId or exerciseSpec is required.
version The published version number of the exercise (number) or 'latest' (default). The latter refers to the current version of the exercise.
exerciseSpec Exercise Definition of the exercise. Either exerciseId or exerciseSpec is required.
level Optional. Difficulty level for the exercise. Applicable for randomized exercise arrangements, which generally offer multiple levels of difficulty. The default value is 0, which represents the lowest level. You can get the number of difficulty levels for the exercise from /exercise-info.
nr Optional. Number of sessions to generate for this exercise. Only relevant for randomized exercises. Default value is 1.
apiVersion Required. Always 2.

Output

The response contains the generated exercises for each element of the input array exercises.

[{
   success: <boolean>
   msg?: <string>
   instances: [{
     success: <boolean>
     msg?: <string>
     exerciseSpec: <Exercise>
     view: <ExerciseView>
   }]
}]
Property Description
success Indicates if generating the nonrandom exercise succeeded.
msg If generating the nonrandom exercise was unsuccessful, 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 solutions for the given sessions. The reply also contains the optimized html code to create and initialize 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>
   type: <string>
   html: <string>
   }]
}]
Property Description
success Indicates if creating the solution for this session succeeded.
msg If creating the solution was not successful, information about the error.
sessionId The ID of the session that corresponds to this solution.
html Optimised html code to create the appropriate web component. This html code already contains the initialization data required by the web component for optimal performance.

Get score

Perform a final evaluation for all interactions in this exercise (if necessary) and retrieve the session results. You can optionally lock the session to prevent any further modifications.

Endpoint: /session/score

Note: Ensure no evaluation events are ongoing when retrieving the score. Learning platforms that use javascript to submit a question should wait before requesting the score.

  await akitExercise.submit(); // wait until the Promise returned by submit() resolves
  // Evaluation is done. It is now safe to retrieve the score

Request Body

{
   sessionId: <string>
   lockSession?: <boolean>
}
Property Description
sessionId ID of the session.
lockSession Set to true to reject future events (evaluation, hint) on this session. Note that it is impossible to unlock the session again.

Output

An exercise can consist of multiple questions (like questions a, b, c, etc.), each containing one or more interactions.

{
   scoring: <ScoringResult>
   questions: [{
      id: <string>
      scoring: <ScoringResult>
      interactions: <InteractionResult>[]
   }]
   tagDescriptions: {<string> : <SkillTagDescription>}
}

<InteractionResult> = {
   id: <string>
   type: <string>
   status: <EvaluationStatus>
   progress: <float>
   scoring: <ScoringResult>
   tags: <SkillTag>[]
   events: <EventData>[]
}

<EventData> =
    {
      event = 'EVALUATE' | 'HINT' | 'GIVEUP'
      timestamp: <long>
      tags: <SkillTag>[]
      annotations: Annotation[]

      //if event  == 'EVALUATE':
      exerciseStatus: <ExerciseStatus>
      inputStatus: <ExpressionStatus> 
      progress: <float> 
    }


<WKDescription> = {
    headLine: ContentElement[];
    subLine?: ContentElement[];
}

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

<SkillTag> = 
  {
     id: <string>
     source: 'ERROR_FEEDBACK' | 'HINT' | 'FINISHED_STEP'
     weight: <float>
     errors?: <string>[]
  }

<SkillTagDescription> = 
  {
     id: <string>
     descr: {lang: <string>}
     stepType: "STRATEGY" | "ALGEBRA" | "CALCULATE" | "ROUND" | "CONCEPT"
     errors?: <ErrorTag>
  }

<ErrorTag> =
  {
     id: <string>
     descr: {lang: <string>}
     type: <ErrorType>[]
  }

<ErrorType> = "MISCONCEPTION" | "MISTAKE"

<Annotation> =
  {
    type: 'HINT' | 'ERROR_FEEDBACK' | 'INPUT_EXPRESSION'
    main?: ContentElement[];
    sub?: ContentElement[];
    expr?: ContentElement[];
  }

<ContentElement> = {
   mimeType: <string>
   content: <string>
}

<ExerciseStatus> = {
   "FINISHED" | "CORRECT" | "ERROR" | "VIRGIN" | "UNKNOWN"
}

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

The output contains the following properties:

Property Description
scoring The total marking for this exercise, based on the results of all interactions.
questions The total marking for each question. Questions are the parts of an exercise, indexed by a, b, c, etc.
tagDescriptions A description of the skills identified in this exercise. The IDs of these tags occur in the results of the various events. You can find more information about detecting mathematical skills here.

The properties of a single interaction are:

Property Description
id The interaction's unique id, or 'ref-id', in this exercise.
type The interaction type.
events An array containing information for every evaluation or hint.
scoring Contains the calculated marking for this interaction based on the evaluations, the hints, and the scoring model.
progress Indicating what percentage of the exercise was completed.
tags A list of tags identifying mathematical skills related to this session. The id in each tag refers to a more detailed description of the skill, which you can find in tagDescriptions. You can find more information about detecting mathematical skills here

The properties of an evaluation event are:

Property Description
exerciseStatus Overall status of the exercise: FINISHED if the question is completed successfully, CORRECT if the question contains valid input but is incomplete, VIRGIN if no work was done, ERROR if the last evaluation contained an error.
inputStatus Evaluation class of the student input. See the table below for more information
progress Indicating what percentage of the exercise was completed.
tags A list of tags identifying mathematical skills related to this event. The id in each tag refers to a more detailed description of the skill, which you can find in tagDescriptions. You can find more information about detecting mathematical skills here.
annotations Textual information about this event, such as error feedback, hint text, or input expression.

Textual information generally consists of text and math elements and is encoded as a list of ContentElement objects. Algebrakit offers two ways to convert this content into HTML; see AlgebraKIT.elements2HTML and akit-content-view.

Scoring results are summarized per interaction, per question, and for the whole exercise.

Property Description
finished Indicates if the student completed the exercise, question, or interaction successfully.
marksTotal The total number of marks the student can earn for this interaction, question, or exercise.
marksEarned The total number of marks that the student got for this interaction, question, or exercise.
penalties Only present on the interaction level. It contains some extra information that explains the scoring for this interaction.

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 not the final answer.
ERROR The input is incorrect, and Algebrakit has diagnosed an error.
NO_MATCH Algebrakit could not 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 could not relate the input to any solution step for this question.
FALSE_EXPRESSION The input is incorrect, such as 2+3=6.

Get results

Retrieve all student actions for the given session, including evaluation results. For example, you can use this information to calculate a student's score based on your scoring scheme. The output is similar to the response of Get score.

Endpoint: /session/result


Lock sessions

Lock or unlock a session. A locked session does not accept new inputs from a student. This functionality is mainly intended for assessments to guarantee nobody changes the results afterward.

There are two types of lock actions. You can later undo a LOCK action with an UNLOCK action. A FINALIZE action locks a session forever.

You can lock or unlock a batch of sessions in a single call.

Endpoint: /sessions/lock

Request Body

{
   action: 'LOCK' | 'UNLOCK' | 'FINALIZE'
   sessionIds: <string>[]
}
Property Description
action 'LOCK': Apply a reversible lock;
'UNLOCK': Unlock a session that was locked with 'LOCK';
'FINALIZE': Lock the session indefinitely.
sessionIds Array of session IDs to lock or unlock.

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 exercise.

{
    commitHistory: CommitData[];
    id: string;
    publishedVersions: <PubVersionInfo>[];
    courseName: string;
    type: string;
}
Property Description
id The exercise ID
type regular exercise if the question is defined by an Exercise Specification (default), single reference if the question is a reference to a question in the question library, arrangement exercise if the question refers to multiple questions in the question library.
<PubVersionInfo> = {
    name: string;
    majorVersion: number | 'latest';
    minorVersion: number;
    metadata: {[key: string]: string};
    numberOfLevels?: number;
    interactions: <InteractionInfo>[];
    resources: <ResourceInfo>[];
}

<CommitData> = {
    versionNumber: string;
    commitDate: Date;
    commitMessage: string;
    authorUsername: string
}

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

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

<QuestionType> = {
   MULTISTEP, 
   FILL_IN_THE_BLANKS, 
   MATH_TABLE, 
   MODEL_METHOD,
   ARITHMETIC,   //Written Arithmetic
   OPEN_ANSWER, 
   CHOICE, 
   STATISTICS,   //Data Analysis
   GEOMETRY,     //Geometry and Graphs
   NUMBER_LINE 
}


Validate exercise

This endpoint checks whether an exercise is valid (i.e., that it runs) and to obtain general information.

Endpoint: /exercise/validate

Request body

{ 
      exerciseId?: <string>
      version?: <string>
      exerciseSpec?: <Exercise>
}
Property Description
exerciseId ID of the exercise in the CMS. Either exerciseId or exerciseSpec is required.
version The published version number of the exercise (number) or 'latest' (default). The latter refers to the current version of the exercise.
exerciseSpec An exercise specification as obtained from the exercise authoring tool

Output

{
   valid: <boolean>
   msg?: <string>
   marks: <number>
   random: <boolean>
   interactions: {[refId: string]:InteractionInfo}
]

InteractionInfo = {
   type: <string>
   marks: <number>
}

Property Description
valid If false, this exercise has a problem and is not suitable to create sessions.
msg A description of the problem in case the exercise is not valid
marks The total number of marks for this exercise
random Indicates whether this exercise is randomized or not
interactions A map with information on the interactions in the exercise. The key is the unique ID of the interaction.