AGGREGATION HTTP INTERFACE

The Learning Locker Aggregation HTTP interface utilises the Mongo aggregation API and is only available for statements. The Aggregation HTTP Interface is more advanced than the xAPI HTTP interface and allows you to access MongoDB’s powerful Aggregation API for more custom filtration of statements.

...

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[{
  "statement": {
    "id": "dfb7218c-0fc9-4dfc-9524-d497097de027",
    "actor": { "objectType": "Agent", "mbox": "mailto:test@example.org" },
    "verb": { "id": "http://www.example.org/verb" },
    "object": { "objectType": "Activity", "id": "http://www.example.org/activity" },
    "version": "1.0.3",
    "authority": { "objectType": "Agent", "mbox": "mailto:authority@example.org" },
    "timestamp": "2017-09-05T12:45:31+00:00",
    "stored": "2017-09-05T12:45:31+00:00"
  }
}]

PIPELINE STAGES

So far we’ve only seen the limit and project stages, however, there are many other stages available in Mongo. The common stages are listed in the table below.

PROJECT STAGE

For example, to project the actor’s account name as a user’s identifier, the verb without a display, and the object’s identifier you can use the following project stage.

...

GET http://www.example.org/api/statements/aggregate?pipeline=%5B%7B%0D%0A%20%20%22%24project%22%3A%20%7B%0D%0A%20%20%20%20%22userId%22%3A%20%22%24statement.actor.account.name%22%2C%0D%0A%20%20%20%20%22statement.verb%22%3A%20%7B%0D%0A%20%20%20%20%20%20%22display%22%3A%200%0D%0A%20%20%20%20%7D%2C%0D%0A%20%20%20%20%22statement.object.id%22%3A%201%0D%0A%20%20%7D%0D%0A%7D%5D
Authorization: Basic YOUR_BASIC_AUTH

PROJECTING WITH EXTENSION KEYS

Note that when using extension keys, you need to replace any dots with &46; because Mongo does not allow dots in keys. For example, when you have an extension key like http://www.example.com/extension you can project it using http://www&46;example&46;com/extension instead, so a project stage using this extension key might look something like the project stage below.

{
  "statement.context.extensions.http://www&46;example&46;com/extension": 1
}

MATCH STAGE

For example, to filter statements by actor or verb, you can use the following match stage.

...

GET http://www.example.org/api/statements/aggregate?pipeline=%5B%7B%0D%0A%20%20%22%24match%22%3A%20%7B%0D%0A%20%20%20%20%22%24or%22%3A%20%5B%7B%0D%0A%20%20%20%20%20%20%22statement.actor.account.name%22%3A%20%22123%22%2C%0D%0A%20%20%20%20%20%20%22statement.actor.account.homePage%22%3A%20%22http%3A%2F%2Fwww.example.org%2Fuser%22%0D%0A%20%20%20%20%7D%2C%20%7B%0D%0A%20%20%20%20%20%20%22statement.verb.id%22%3A%20%7B%0D%0A%20%20%20%20%20%20%20%20%22%24in%22%3A%20%5B%0D%0A%20%20%20%20%20%20%20%20%20%20%22http%3A%2F%2Fwww.example.org%2Fverb%22%2C%0D%0A%20%20%20%20%20%20%20%20%20%20%22http%3A%2F%2Fwww.example.org%2Fotherverb%22%0D%0A%20%20%20%20%20%20%20%20%5D%0D%0A%20%20%20%20%20%20%7D%0D%0A%20%20%20%20%7D%5D%0D%0A%20%20%7D%0D%0A%7D%5D
Authorization: Basic YOUR_BASIC_AUTH

MATCHING WITH EXTENSION KEYS

Note that when using extension keys, you need to replace any dots with &46; because Mongo does not allow dots in keys. For example, when you have an extension key like http://www.example.com/extension you can filter it using http://www&46;example&46;com/extension instead, so a match stage using this extension key might look something like the match stage below.

{
  "statement.context.extensions.http://www&46;example&46;com/extension": {
    "$ne": "example_value"
  }
}

MATCHING ON OBJECTIDS

When querying on ObjectIds we must tell the aggregation to cast these values. To do this we can use the $oid operator:

...

This will cast the ID to a Mongo Object ID

MATCHING ON BINARY DATE FIELDS

Most date fields (other than statement.timestamp and statement.stored) are stored as ISODate values. To query on these we can cast our ISO8601 formatted date from a string into an ISODate using the $dte operator:

// return all records in April 2017
"timestamp": {
  "$gte": {
    "$dte": "2017-04-01T00:00:00Z"
  },
  "$lt": {
    "$dte": "2017-05-01T00:00:00Z"
  }
}

MATCHING WITH IMPROVED PERFORMANCE

You may find that changing the match stage can vary the time it takes a query to run, especially when you have a large number of statements. You can take advantage of database indexes to improve performance, more information is available about using indexes in the match stage via Mongo’s documentation. If utilising indexes doesn’t have the required performance improvement, you can instead utilise our Connection HTTP Interface or BI tools.

LIMIT STAGE

For example, to limit the interface to returning 1 statement, you can use the following request. You can find out more about the limit stage via the Mongo documentation.

GET http://www.example.org/api/statements/aggregate?pipeline=%5B%7B%20%22%24limit%22%3A%201%20%7D%5D
Authorization: Basic YOUR_BASIC_AUTH

SKIP STAGE

For example, to skip the first statement, you can use the following request. You can find out more about the skip stage via the Mongo documentation.

GET http://www.example.org/api/statements/aggregate?pipeline=%5B%7B%20%22%24skip%22%3A%201%20%7D%5D
Authorization: Basic YOUR_BASIC_AUTH

GROUP STAGE

For example, to retrieve the average raw score for each actor, you can use the group stage below.

...

GET http://www.example.org/api/statements/aggregate?pipeline=%5B%7B%0A%20%20%22%24group%22%3A%20%7B%0A%20%20%22_id%22%3A%20%7B%0A%20%20%20%20%22actor_account_homePage%22%3A%20%22%24statement.actor.account.homePage%22%2C%0A%20%20%20%20%22actor_account_name%22%3A%20%22%24statement.actor.account.name%22%2C%0A%20%20%20%20%22actor_mbox%22%3A%20%22%24statement.actor.mbox%22%2C%0A%20%20%20%20%22actor_mbox_sha1sum%22%3A%20%22%24statement.actor.mbox_sha1sum%22%2C%0A%20%20%20%20%22actor_openid%22%3A%20%22%24statement.actor.openid%22%0A%20%20%7D%2C%0A%20%20%22statements%22%3A%20%7B%20%22%24avg%22%3A%20%22%24statement.result.score.raw%22%20%7D%0A%7D%0A%7D%5D
Authorization: Basic YOUR_BASIC_AUTH

GROUPING WITH EXTENSION KEYS

Note that when using extension keys, you need to replace any dots with &46; because Mongo does not allow dots in keys. For example, when you have an extension key like http://www.example.com/extension you can group by it using http://www&46;example&46;com/extension instead, so a group stage using this extension key might look something like the group stage below.

{
  "_id": "$statement.context.extensions.http://www&46;example&46;com/extension",
  "statements": { "$avg": "$statement.result.score.raw" }
}

SORT STAGE

In this stage the keys of the object represent the names of the properties you wish to sort. The values of the object represent the order in which you want to sort the properties. To sort in ascending order, use the number 1; to sort in descending order, use the number -1. For example, to sort statements in descending order of their timestamp and ascending order of their Mongo ObjectId, you can use the following sort parameter.

...

GET http://www.example.org/api/statements/aggregate?pipeline=%5B%7B%0D%0A%20%20%22%24sort%22%3A%20%7B%0D%0A%20%20%20%20%22timestamp%22%3A%20-1%2C%0D%0A%20%20%20%20%22_id%22%3A%201%0D%0A%20%20%7D%0D%0A%7D%5D
Authorization: Basic YOUR_BASIC_AUTH

SORTING WITH EXTENSION KEYS

Note that when using extension keys, you need to replace any dots with &46; because Mongo does not allow dots in keys. For example, when you have an extension key like http://www.example.com/extension you can sort by it using http://www&46;example&46;com/extension instead, so a sort stage using this extension key might look something like the sort stage below.

{
  "statement.context.extensions.http://www&46;example&46;com/extension": 1
}

SORTING WITH IMPROVED PERFORMANCE

You may find that changing the sort stage can vary the time it takes a query to run, especially when you have a large number of statements. You can take advantage of database indexes to improve performance, more information is available about using indexes in the sort stage via Mongo’s documentation. If utilising indexes doesn’t have the required performance improvement, you can instead utilise our Connection HTTP Interface or BI tools.