Submit a request
Submit a request

Getting Started With the Data API

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.

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

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

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.

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.

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. 

<?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

 


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