All interaction data stored in Watershed takes the form of xAPI statements. This includes both data from native xAPI sources and also data translated from imported CSV files. The Data Export API enables you to pull those interaction statements via API with the full flexibility of Watershed filters. This is considerably more powerful than the Statements API defined by the xAPI specification (which Watershed also supports).
Related: The Data Export API returns the underlying xAPI data for a filter. If you want to pull aggregated data instead, you should use the Aggregation API.
Connecting to the Data Export API
Our family of REST APIs are made accessible through a secure SSL connection over HTTP, using basic authentication. To connect to Watershed’s API you need a set of credentials and organization id (unless you are creating an organization, then you don’t need the id).
To create a set of credentials, see How do I add an activity provider to Watershed? You are able to choose if credentials have access to the LRS API, the Reporting API or both.
This is passed to the API using Basic HTTP Authentication. In addition to the Authorization header required for Basic Authentication, all POST and PUT requests must have a Content-Type header with the value application/json.
The easiest way to find the organization id is to log in to Watershed and go to the Settings/Data page. The organization id is included within the Watershed LRS Endpoint URL. For example if the endpoint URL is https://watershedlrs.com/api/organizations/1234/lrs/ then the organization id is 1234.
Data Export API Details
Request URL: /api/organizations/[org-id]/query/export
Method: GET
Expected response code: 200 OK
Request parameters
|
Parameter |
Details |
|
type |
The type of file to return, either ‘json’ or ‘csv’. |
|
filter |
A urlencoded filter object with the same properties as can be used in card and measure filters. If you copy this from a card’s advanced configuration, remember to strip out the white space before url encoding the filter string. |
|
cardId |
The id of a card to use the filter from. |
The type parameters is required along with either filters or cardId parameters. If both cardId and filters are specified, only cardId will be used and filters will be ignored.
Response
A successful response will return either a json or csv document containing the xAPI statements. If the type is json, then the json file will contain valid xAPI statements. If the type is csv, the csv file will contain most or all of the data from the statements in tabular format with one statement on each row.
Examples
These examples are presented in Python 3.
import requests
ws_key = "your_watershed_key"
ws_secret = "your_watershed_secret"
url = "https://sandbox.watershedlrs.com/api/organizations/1234/query/export?"
url += '''filter={"activityIds":{"ids":["http://video.portal.example.com/search"]}}'''
url += "&type=json"
r = requests.get(url, auth=(ws_key, ws_secret), timeout=120)
# Using Card ID instead of a filter
import requests
ws_key = "your_watershed_key"
ws_secret = "your_watershed_secret"
url = "https://sandbox.watershedlrs.com/api/organizations/1234/query/export?cardId=1234&type=csv"
r = requests.get(url, auth=(ws_key, ws_secret), timeout=120)