API for the LLN Robot System
Purpose
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. |
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. |