Getting Started With the Data API

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:

  1. Your app sends a resource request to one of the Learnosity endpoints (via the Learnosity SDK). 
  2. The endpoint then returns a response to your app in the form of a JSON object.
  3. 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:

  1. The learner or student that we are reporting on, referenced with “user_id”. For this example, we'll use “student_0001”.  We will request the data using this identifier. 
    Note: you should never send or save student's names or any other personally identifiable information in these requests. The unique identifier should be used to look up the entry in a database of students accessible within your system only, so that no personally identifiable information is stored on the Learnosity server. Learn more.

  2. You could also request the specific assessment or exam that you want, referenced with “session_id” (you can think of a “session” as the data generated by one learner going through an 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. 

data_api_demos.png

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”. 

fields_in_demo.png

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. 

response_json.png

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:

 

request_json.pngScreenshot 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:

  1. "consumer_key" is the identifier for the Learnosity account (broadly speaking) that is in use. 
  2. "domain" is the Internet web domain where the app is running (which calls Learnosity).
  3. "timestamp" is the time when the request was sent.
  4. "signature" is the request signature.

 

Under the "request" section:

  1. "user_id": the learner whose data will be retrieved.
  2. "mintime": the beginning of the time frame for retrieved data.
  3. "maxtime": the end of the time frame for retrieved data.
  4. "sort": "asc": selects ascending sort order for the returned data.
  5. "limit": controls the number of entries returned.

Note: the format of these requests varies depending on which endpoint you are using. In this case, we are using the sessions/responses/scores endpoint. There's additional documentation explaining the other endpoints.

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. 

Note: Learnosity is not a REST API. All HTTP calls to the API need to be in the form of a POST operation. The fifth argument in the result setup block can be either "get", "set" or "update". We're using "get" in this example.

<?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, 
// and 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()); 
// Note, you can also use getJson() in the line above to return more easily 
// manipulated data.

Code sample 1: quickstart get example using Data API

 

Now that you've seen a "get" example, the following example uses the "set" action type, with the "itembank/questions" endpoint, to store some new Question JSON into the Item bank.

<?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, 
// and 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 itembank/questions.
$itembank_uri = 'https://data.learnosity.com/v2023.1.LTS/itembank/questions'; 

// 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 = [
'questions' => [
   [
      'type' => 'mcq',
      'reference' => 'dataapi_test_001',
      'data' => [
         'options' => [
         [
            'value' => '0',
            'label' => 'John will have more apples and more oranges than Lucy.'
         ],
         [
            'value' => '1',
            'label' => 'John will have less apples and less oranges than Lucy.'
         ],
         [
            'value' => '2',
            'label' => 'John will have more apples than Lucy, but Lucy has more oranges.'
         ],
         [
            'value' => '3',
            'label' => 'John will have more oranges than Lucy, but Lucy has more apples.'
         ]
         ],
         'stimulus' => 'This is the stem',
         'type' => 'mcq',
         'validation' => [
            'scoring_type' => 'exactMatch',
            'valid_response' => [
               [
                  'value' => [
                     '0'
                  ],
               'score' => 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,
   'set'
);

// 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()); 
// Note, you can also use getJson() in the line above to return more easily 
// manipulated data.

Code sample 2: quickstart set example using Data API

 

The full source code for the example above (and others) can be found on our Github repository. 

 

Next Steps

  • See our Data API demo page to learn more about Data API request structures and see more of the Data API in action.
  • See our Data API endpoints page on our Reference documentation site for more in-depth information on the commands and capabilities that are available. 

 

Was this article helpful?

Related articles


Did you arrive here by accident? If so, learn more about Learnosity.