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.