API for the LLN Robot System

Purpose

The LLN Robot System API can be used by developers to extend the LLN Robot System to further meet your organization's needs. The LLN Robot System API acts as an interface for external clients to access deployment-specific information from the LLN Robot System. Requests are made using HTTP and are used to extract information from the database.
For example, the LLN Robot System API can be used to access all of the learner information available within your LLN Robot System. Using the LLN Robot System API you can send an HTTP request and receive all of the learner details as a response. This can then be configured for use by external systems such as LMS or accounting software.
URL

http://api.lln.training/api/[deployment]/[version]/[resource]?since=[date]

Where the variables inside [] need to be replaced for the correct response.

deployment - the deployment name that is assigned to the client to access the LLN Robot.

version - the API version that you want to access, currently there is only one version of the API available,  'v1'.

resource - the kind of resource information that you want to access from the system, in this case, it is 'learners' since we are accessing all the learner's information.

date - a UTC date in JSON format. If this is included, the API will only return learners who have had their data updated since this date/time.

An example data is given for your reference in order to use the API:

http://api.lln.training/api/testing/v1/learners?since=2019-01-01T00:00:00Z

This URL along with the authentication will return the active learners’ information that has been changed since January 1st 2019.

Data Formats

The response from the API returns a JSON document.

At this time, JSON is the only format that we support, therefore you will need to take it into consideration when displaying the data.

Response Codes

Response Code Definition
200 No Errors. Data should be fetched.
400 Bad Request. There is a mistake in the URL that you entered.
Please check and make sure the version and the resource are spelt and placed correctly.
401 Unauthorized. You’ve entered the wrong API Key.
404 Not Found. The URL that you have entered is incorrect, please check the different parameters of the URL

Authentication Type - What’s Expected in a request

When creating a request, we require the API Key to be passed in a header parameter with key Authorization. For example:

Header Key: Authorization

Header Value: ROBOT-V1-KEY apikey="{your api key}"

The API Key can be found in the front-end of your system on the 'Manage System Settings' screen.

You will need to first enable the API to access it. If you are not an administrator of the system, you will need to ask one of the administrators for your deployments specific API Key.

If you believe that your API Key has been compromised, contact The Learning Resources Group and we can reset it for you.

HTTP Methods

HTTP Method Use
GET Fetching a list of records.

API Endpoints

Learners:

/api/[deployment]/v1/learners

Returned Properties:

Property Name Type Use
inviteCode UniqueIdentifier Uniquely identifies the quiz results.
learnerId string The learnerId from your deployment (if entered).
Please note: the same learnerId may be on several results if learner has redone the quiz or completed multiple quizzes.
name.first string The first name of the learner.
name.last string The last name of the learner.
email string The email address of the learner.
results Object ACSF 3/4: The results object contains 5 key-value pairs which display their ACSF scores for each section.
ACSF 3 Short Course:  The results object contains 3 key-value pairs which display their ACSF scores for each section.
VSL: The results object contains 2 key-value pairs which display the reading and numeracy scores
complete boolean Is true if the learner has completed the quiz. Is false if the learner hasn’t.
details Array<Object> The details object includes all custom fields that the administrators of the deployment want learners to fill out.
testLevel string The quiz that the learner has been invited to.
updatedAt Date JSON formatted UTC date/time this record was last updated.

Still need help? Contact Us Contact Us