Data API provides developers with direct access to specific data inside the Learnosity environment. This data can be extracted, transformed, sent back to the cloud, or used in your own application logic and presentation.
When using Data API, the sequence of events is usually like this:
- Your app sends a resource request to one of the Learnosity endpoints (via the Learnosity SDK).
- The endpoint then returns a response to your app in the form of a JSON object.
- Your app takes the data from the JSON object and does whatever you'd like to do with it.
Sending Requests to Data API
Let's take a look at a simple request with Data API.
For this example, we'll pull some data on specific learner's assessment results, which is stored in the form of a "session".
In this example, we have already created an example set of four learners, who each completed an assessment of ten Questions, a mixture of Science and English subjects.
To extract one of these assessment summaries, we will need the following information:
- The learner or student that we are reporting on, referenced with “user_id”. For this example, we'll use “student_0001” (note – learners are always identified with a de-identified unique name, so that no personally identifiable data is stored on the Learnosity server). We will request the data using this identifier.
- You could also request the specific assessment or exam that we want, referenced with “session_id” (you can think of a “session” as one assessment or exam). For this example, you could use “ef4f80b8-e281-41f4-9efd-349b7eb9dd37”. We'll show how to do that in later examples.
We can take a look at what Data API returns by working with our Data API Demo page – open this link in a new browser window.
Screenshot 1: the Learnosity Data API demo page
From here, select the option (endpoint) under “Sessions > ACTION-GET /v2023.1.LTS/sessions/responses > Request Form tab > users field”, then enter “student_0001” into the “user(s)” field, set the "mintime" field to "2011-01-01" and click “submit”.
Screenshot 2: selecting a URL endpoint, username, and mintime values.
The raw data from the assessment set will be loaded and displayed, in JSON format.
Screenshot 3: the response data from Data API
You can view data from other students by submitting “student_0002”, “student_0003” or “student_0004” in the same way.
Note: this data belongs to the open Learnosity demo account, which only holds demonstration data.
The request format that Data API expects
Now we'll go over the specific request format that Data API expects to receive from your app.
If you click the "Response" tab back on the demo page, you can see the request JSON, which was sent to Data API, which looks like this:
Screenshot 4: the request JSON that was sent to Data API
When you programmatically access the Data API, you will send it requests in this JSON format. In Screenshot 4, you can see the "user_id" and the "mintime" values that you specified, along with others.
Under the "security" section:
- "consumer_key" is the identifier for the Learnosity account (broadly speaking) that is in use.
- "domain" is the Internet web domain where the app is running (which calls Learnosity).
- "timestamp" is the time when the request was sent.
- "signature" is the request signature.
Under the "request" section:
- "user_id": the learner whose data will be retrieved.
- "mintime": the beginning of the time frame for retrieved data.
- "maxtime": the end of the time frame for retrieved data.
- "sort": "asc": selects ascending sort order for the returned data.
- "limit": controls the number of entries returned.
Quick Start Guide
Now, we'll build a small example program in your language of choice, that makes the same request to Data API that we used in the preceding section.
Requirements and Installation
To use Data API, you will need the Learnosity SDK installed to make requests to the Learnosity system. The Learnosity SDK provides an essential signature generation capability.
Choose your favorite language below and visit the Learnosity SDK GitHub repository page to install the SDK and get you up and running. Full instructions are included in the README tutorials in each SDK repository.
After installation, when you have the SDK installed and tested for your language, return to this page and continue.
Running your first Data API request in code
We'll now take the same JSON request we could see on the demo page, and write it into your own code example to query the same data from Data API. It will perform the same action we did earlier, that is to retrieve the session information for "student_0001", then show the responses that learner gave to Questions in the assessment.
Let's walk through the PHP code for this example, step by step.
<?php
/* Copyright (c) 2023 Learnosity, MIT License
Basic example code for pulling information from the Learnosity cloud using Data API. */
/* Setup block, to load the necessary classes from the example directory, & set up variables for access. */
require_once __DIR__ . '/../../../bootstrap.php';
/* Load security keys from local file config.php, for Learnosity's public demos account. */
$config = require_once __DIR__ . '/../config.php';
// Load core Data API library.
use LearnositySdk\Request\DataApi;
// Choosing the Data API endpoint for sessions/responses.
$itembank_uri = 'https://data.learnosity.com/v2023.1.LTS/sessions/responses';
// Selecting the Learnosity account (consumer key).
$consumerKey = $config['consumerKey'];
// Note: Learnosity will provide keys for your own private account.
$security_packet = [
// Selecting the Learnosity account (consumer key).
'consumer_key' => $consumerKey,
/* Selecting the domain where your app will be resident ('localhost' is for testing local code). */
'domain' => 'localhost',
];
/* Providing the password for the Learnosity account from the configuration file. */
$consumer_secret = $config['consumerSecret'];
// Essential step of initializing the API
$data_api = new DataApi();
/* Request setup block. Creates a variable holding the Data API request options as JSON. */
$data_request = [
'user_id' => ['student_0001'],
'mintime' => '2020-01-01',
'maxtime' => '2020-12-31',
'limit' => 1
];
/* Result setup block. Compiles all of the security configuration and request options together, then calls Data API to get the data. */
$result = $data_api->request(
$itembank_uri,
$security_packet,
$consumer_secret,
$data_request,
'get'
);
// Printout block. Printing the output into the browser window.
// Convert the request data to JSON format.
$response = $result->json();
// Get the HTTP status code that the request returned, and add it to the data.
echo "<<< [{$result->getStatusCode()}]" . PHP_EOL;
// Print the returned data into the browser window.
print_r($result->getBody());
Code sample 1: quickstart example using Data API
The full source code for the example above (and others) can be found on our Github repository.
Note: Learnosity is not a REST API. All HTTP calls to the API need to be in the form of a POST operation.
Next Steps