Extended APIs


Introduction

As you may know, the xAPI specification defines standard APIs which have some limitations. TRAX LRS provides extended APIs which give you more options to manipulate xAPI data.

Prerequisites

In order to acces the extended APIs, 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 APIs.

Statements API

Model

Property Description
id Internal database ID
uuid Statement UUID
data Statement JSON
voided Is the statement voided?
owner_id ID of the owner (i.e. the store) the data belongs to
entity_id ID of the entity the data belongs to
client_id ID of the client the data belongs to
access_id ID of the access the data came from
created_at Creation timestamp
updated_at Last update timestamp

POST /statements

Create a statement with the following data:

Property Description
data Statement JSON
voided Boolean (default: false)

PUT /statements/:id

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

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
magicActor Advanced search in the statement actor
magicVerb Advanced search in the statement verb
magicObject Advanced search in the statement object
magicContext Advanced search in the statement context

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

Model

Property Description
id Internal database ID
iri Activity IRI
data Activity JSON
owner_id ID of the owner (i.e. the store) the data belongs to
created_at Creation timestamp
updated_at Last update timestamp

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
magic Advanced search

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

Model

Property Description
id Internal database ID
vid Virtual ID based on the xAPI identification
data Agent JSON
pseudonymized Is it a pseudonymized agent?
person_id ID of the person the agent refers to
pseudo_id ID of the matching pseudonymized agent
owner_id ID of the owner (i.e. the store) the data belongs to
created_at Creation timestamp
updated_at Last update timestamp

POST /agents

Create an agent with the following data:

Property Description
data 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
magic Advanced search

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.

Activity Profiles API

Model

Property Description
id Internal database ID
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)
owner_id ID of the owner (i.e. the store) the data belongs to
entity_id ID of the entity the data belongs to
client_id ID of the client the data belongs to
access_id ID of the access the data came from
created_at Creation timestamp
updated_at Last update timestamp

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.

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

Model

Property Description
id Internal database ID
profile_id ID of the profile as stated by xAPI (string)
vid Virtual ID of the agent, based on the xAPI identification
agent Agent (JSON)
data JSON object with 2 properties: type (MIME type) and content (data)
owner_id ID of the owner (i.e. the store) the data belongs to
entity_id ID of the entity the data belongs to
client_id ID of the client the data belongs to
access_id ID of the access the data came from
created_at Creation timestamp
updated_at Last update timestamp

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.

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

Model

Property Description
id Internal database ID
state_id ID of the state as stated by xAPI (string)
activity_id ID of the activity as stated by xAPI (IRI)
vid Virtual ID of the agent, based on the xAPI identification
agent Agent (JSON)
registration Registration as stated by xAPI (UUID)
data JSON object with 2 properties: type (MIME type) and content (data)
owner_id ID of the owner (i.e. the store) the data belongs to
entity_id ID of the entity the data belongs to
client_id ID of the client the data belongs to
access_id ID of the access the data came from
created_at Creation timestamp
updated_at Last update timestamp

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.

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

Model

Property Description
id Internal database ID
data Attachment JSON
owner_id ID of the owner (i.e. the store) the data belongs to
entity_id ID of the entity the data belongs to
client_id ID of the client the data belongs to
access_id ID of the access the data came from
created_at Creation timestamp
updated_at Last update timestamp

POST /attachments

Create an attachment with the following data:

Property Description
data Attachment JSON

PUT /attachments/:id

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

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

Model

Property Description
id Internal database ID
uuid Person UUID
owner_id ID of the owner (i.e. the store) the data belongs to
created_at Creation timestamp
updated_at Last update timestamp

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

Model

Property Description
id Internal database ID
iri Verb identity as stated by xAPI (IRI)
owner_id ID of the owner (i.e. the store) the data belongs to
created_at Creation timestamp
updated_at Last update timestamp

POST /verbs

Create a verb with the following data:

Property Description
iri Verb identity 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
magic Advanced search

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.

Stores API

DELETE /stores

Delete all the stores and respective xAPI data.

DELETE /stores/:id

Delete a store and respective xAPI data.

Request Parameters

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"