Extended API

Introduction

As you may know, the xAPI specification defines a standard API which has some limitations. TRAX LRS provides an extended API which gives you more options to manipulate xAPI data.

This API relies on TRAX LRS data models.

Prerequisites

In order to acces the extended API, you must create a client and access with extra permissions:

  • Observe xAPI data if you just need to read data
  • Manage xAPI data if you need both to read and write data

Then, get the access endpoint and replace std by ext at the end of the URL. You have now the endpoint of the extended API.

Statements API

GET /statements/:id

Get a statement given its internal database ID.

GET /statements

Get the statements matching with the request parameters as specified at the end of this document.

This API provides additional filters:

Parameter Description
uiActor Search on the actor (see UI field)
uiVerb Search on the verb (see UI field)
uiObject Search on the object (see UI field)
uiContext Search on the context (see UI field)
statementId As defined by the xAPI spec
voidedStatementId As defined by the xAPI spec
agent As defined by the xAPI spec
verb As defined by the xAPI spec
activity As defined by the xAPI spec
registration As defined by the xAPI spec
related_activities As defined by the xAPI spec
related_agents As defined by the xAPI spec
since As defined by the xAPI spec
until As defined by the xAPI spec

This API provides specific options:

Parameter Description
reveal Reveal the returned statements if they were pseudonymized

GET /statements/count

Count the statements matching with the request parameters as specified at the end of this document.

DELETE /statements/:id

Delete a statement given its internal database ID.

DELETE /statements

Delete the statements matching with the request parameters as specified at the end of this document.

Activities API

POST /activities

Create an activity with the following data:

Property Description
data Activity JSON

PUT /activities/:id

Update an activity given its internal database ID. Data is the same than POST requests.

GET /activities/:id

Get an activity given its internal database ID.

GET /activities

Get the activities matching with the request parameters as specified at the end of this document.

This API provides additional filters:

Parameter Description
uiCombo Advanced search (see UI field)
activityId As defined by the xAPI spec

GET /activities/count

Count the activities matching with the request parameters as specified at the end of this document.

DELETE /activities/:id

Delete an activity given its internal database ID.

Agents API

POST /agents

Create an agent with the following data:

Property Description
agent Agent JSON
pseudonymized Is it a pseudonymized agent?
person_id ID of the person the agent refers to

PUT /agents/:id

Update an agent given its internal database ID. Data is the same than POST requests.

GET /agents/:id

Get an agent given its internal database ID.

GET /agents

Get the agents matching with the request parameters as specified at the end of this document.

This API provides additional filters:

Parameter Description
uiCombo Advanced search (see UI field)
uiObjectType Object type: Agent or Group
uiName Full or partial name
agent As defined by the xAPI spec

GET /agents/count

Count the agents matching with the request parameters as specified at the end of this document.

DELETE /agents/:id

Delete an agent given its internal database ID.

DELETE /statements

Delete the agents matching with the request parameters as specified at the end of this document.

Activity Profiles API

POST /activity_profiles

Create an activity profile with the following data:

Property Description
profile_id ID of the profile as stated by xAPI (string)
activity_id ID of the activity as stated by xAPI (IRI)
data JSON object with 2 properties: type (MIME type) and content (data)

PUT /activity_profiles/:id

Update an activity profile given its internal database ID. Data is the same than POST requests.

GET /activity_profiles/:id

Get an activity profile given its internal database ID.

GET /activity_profiles

Get the activity profiles matching with the request parameters as specified at the end of this document.

This API provides additional filters:

Parameter Description
uiActivity Full or partial activity ID
uiProfile Full or partial profile ID
profileId As defined by the xAPI spec
activityId As defined by the xAPI spec
since As defined by the xAPI spec

GET /activity_profiles/count

Count the activity profiles matching with the request parameters as specified at the end of this document.

DELETE /activity_profiles/:id

Delete an activity profile given its internal database ID.

Agent Profiles API

POST /agent_profiles

Create an agent profile with the following data:

Property Description
profile_id ID of the profile as stated by xAPI (string)
agent Agent JSON
data JSON object with 2 properties: type (MIME type) and content (data)

PUT /agent_profiles/:id

Update an agent profile given its internal database ID. Data is the same than POST requests.

GET /agent_profiles/:id

Get an agent profile given its internal database ID.

GET /agent_profiles

Get the agent profiles matching with the request parameters as specified at the end of this document.

This API provides additional filters:

Parameter Description
uiAgent Advanced search on agent (see UI field)
uiProfile Full or partial profile ID
profileId As defined by the xAPI spec
agent As defined by the xAPI spec
since As defined by the xAPI spec

GET /agent_profiles/count

Count the agent profiles matching with the request parameters as specified at the end of this document.

DELETE /agent_profiles/:id

Delete an agent profile given its internal database ID.

States API

POST /states

Create a state with the following data:

Property Description
state_id ID of the state as stated by xAPI (string)
activity_id ID of the activity as stated by xAPI (IRI)
agent Agent JSON
registration Registration as stated by xAPI (UUID)
data JSON object with 2 properties: type (MIME type) and content (data)

PUT /states/:id

Update a state given its internal database ID. Data is the same than POST requests.

GET /states/:id

Get a state given its internal database ID.

GET /states

Get the states matching with the request parameters as specified at the end of this document.

This API provides additional filters:

Parameter Description
uiAgent Advanced search on agent (see UI field)
uiActivity Full or partial activity ID
uiState Full or partial state ID
stateId As defined by the xAPI spec
activityId As defined by the xAPI spec
agent As defined by the xAPI spec
since As defined by the xAPI spec

GET /states/count

Count the states matching with the request parameters as specified at the end of this document.

DELETE /states/:id

Delete a state given its internal database ID.

Attachments API

GET /attachments/:id

Get an attachment given its internal database ID.

GET /attachments

Get the attachments matching with the request parameters as specified at the end of this document.

GET /attachments/count

Count the attachments matching with the request parameters as specified at the end of this document.

DELETE /attachments/:id

Delete an attachment given its internal database ID.

Persons API

POST /persons

Create a person with the following data:

Property Description
owner_id ID of the owner (i.e. the store) the data belongs to

PUT /persons/:id

Update a person given its internal database ID. Data is the same than POST requests.

GET /persons/:id

Get a person given its internal database ID.

GET /persons

Get the persons matching with the request parameters as specified at the end of this document.

GET /persons/count

Count the persons matching with the request parameters as specified at the end of this document.

DELETE /persons/:id

Delete a person given its internal database ID.

Verbs API

POST /verbs

Create a verb with the following data:

Property Description
iri Verb id as stated by xAPI (IRI)

PUT /verbs/:id

Update a verb given its internal database ID. Data is the same than POST requests.

GET /verbs/:id

Get a verb given its internal database ID.

GET /verbs

Get the verbs matching with the request parameters as specified at the end of this document.

This API provides additional filters:

Parameter Description
uiCombo Advanced search (see UI field)

GET /verbs/count

Count the verbs matching with the request parameters as specified at the end of this document.

DELETE /verbs/:id

Delete a verb given its internal database ID.

Activity Types API

POST /activity_types

Create an activity type with the following data:

Property Description
iri Activity type id as stated by xAPI (IRI)

PUT /activity_types/:id

Update an activity type given its internal database ID. Data is the same than POST requests.

GET /activity_types/:id

Get an activity type given its internal database ID.

GET /activity_types

Get the activity types matching with the request parameters as specified at the end of this document.

This API provides additional filters:

Parameter Description
uiCombo Advanced search (see UI field)

GET /activity_types/count

Count the activity types matching with the request parameters as specified at the end of this document.

DELETE /activity_types/:id

Delete an activity type given its internal database ID.

Statement Categories

POST /statement_categories

Create a statement category with the following data:

Property Description
iri Statement category id as stated by xAPI (IRI)
profile Is this category identified as an xAPI profile?

PUT /statement_categories/:id

Update a statement category given its internal database ID. Data is the same than POST requests.

GET /statement_categories/:id

Get a statement category given its internal database ID.

GET /statement_categories

Get the statement categories matching with the request parameters as specified at the end of this document.

This API provides additional filters:

Parameter Description
uiCombo Advanced search (see UI field)

GET /statement_categories/count

Count the statement categories matching with the request parameters as specified at the end of this document.

DELETE /statement_categories/:id

Delete a statement category given its internal database ID.

Stores API

DELETE /stores/:id

Delete a store and all its data.

POST /stores/:id/clear

Remove all the xAPI data from a store.

POST /stores/:id/statements/clear

Remove the statements from a store.

Request Parameters

In order to improve the readability of this chapter, we illustrate the use of HTTP parameters in a Javascript way, as most Javascript HTTP clients would do (e.g. Axios).

sort

This parameter takes an array of property names from the requested model. By default, sorting is ascending. Adding the minus sign makes it descending.

{
    sort: ["id"]        // Sort by the id, ascending
}
{
    sort: ["-id"]       // Sort by the id, descending
}

limit

This parameter takes an integer which is the number of returned items.

{
    limit: 10           // Don't return more than 10 items
}

skip

This parameter takes an integer which is the number of items to skip.

{
    skip: 3000           // Don't return the 3000 first items
}

after

This parameter takes an object which identifies the starting item. Only items after the starting item are returned, in the ascending order.

{
    after: {id: 200}           // Return items after ID 200 in the ascending order
}

before

This parameter takes an object which identifies the starting item. Only items before the starting item are returned, in the descending order.

{
    before: {id: 400}           // Return items before ID 400 in the descending order
}

options

This parameter takes an object defining options for a given request. Options are specific to each API.

{
    options: {reveal: true}       // Reveal the returned statements if they were pseudonymized
}

filters

This parameter takes an object of filters to be applied.

Filtering on model properties

{
    filters: {voided: true}       // Return only the voided statements
}

Filtering on a JSON property

{
    filters: {"data->version": "1.0.0"}       // Return only statements with version 1.0.0
}

Comparison operators

{
    filters: {"data->version": {$gte: "1.0.0"}       // Return only statements with version from 1.0.0
}
Operator Description
$eq Equal
$gt Greater than
$gte Greater than or equal
$lt Less than
$lte Less than or equal
$ne Not equal
$in In array
$nin Not in array
$text Textual search
$exists Exists and not null

Logical operators

{
    filters: {voided: true, "data->version": "1.0.0"}            // Implicit AND condition
}
{
    filters: {$and: {voided: true, "data->version": "1.0.0"}}    // Explicit AND condition
}
{
    filters: {$or: {voided: true, "data->version": "1.0.0"}}     // Explicit OR condition
}

JSON contains operator

Use [*] to search a value in a JSON array.

{
    filters: {"meta->hobbies[*]": "photo"}          // Return items with "photo" in their hobbies
}
{
    filters: {"meta->children[*]->name": "john"}    // Return items with a child named "john"
}
{
    filters: {"meta->children[*]": {"name": "john", "age": 10}}    // Return items with a 10 years old child named "john"
}

JSON search operator

Use [*] together with the $text operator.

{
    filters: {"meta->children[*]->name": {$text: "jo"}}    // Return items with a child name containing "jo"
}