Course Provisioning and Setup API's
Course and Class Provisioning
To create a course online, instead of using our API, go to: http://www.openlearning.com/courses/create/
Provision a New Course
API Method (POST, GET):
https://www.openlearning.com/api/provision/course/<New Course Path>
POST Parameters:
title A string containing the course title (e.g. "How to Draw Horses")
category A category which this course may belong to (e.g. "Art")
e.g.
curl -f -u "${USERNAME}:${PASSWORD}" "https://www.openlearning.com/api/provision/course/${NEW_COURSE_PATH}" -d "title=How to Draw Horses" -d "category=Art"
This will return a JSON object which looks like:
{
"success": true,
"path": "courses/myNewCourse",
"url": "https://www.openlearning.com/courses/myNewCourse"
}
Provision a New Class within an Existing Course
API Method (POST, GET):
https://www.openlearning.com/api/provision/class/<Existing Course Path>
POST Parameters:
title A string containing the class title (e.g. "First Semester")
type Either:
"open" - anyone can join the class
"requires-activation-code" - only those with an activation code may enrol
"invite-only" - only those invited to join may enrol
"closed" - no-one can join this class yet
isBilled "true" or "false" - depending on whether students need to pay for this class
studentPrice A number, e.g. "12.00" which is the price to charge students
currency e.g. "USD" or "AUD"
activationCode A code which users need in order to join the class e.g. "My Secret Code"
startDate When this class starts, an ISO 8601 date/time string
e.g.
curl -f -u "${USERNAME}:${PASSWORD}" "https://www.openlearning.com/api/provision/class/${COURSE_PATH}" -d "title=First Class" -d "type=open"
This will return a JSON object which looks like:
{
"success": true,
"class": {
"path": "courses/myCourse/Cohorts/FirstClass",
"title": "First Class",
"type": "open"
}
}
Course Class Setup
Change the Online/Offline Status of a Course
API Method (POST, GET)
https://www.openlearning.com/api/course/status/<Course Path>
POST Parameters
status=online
or
status=offline
e.g. to take a course offline:
curl -f -u "${USERNAME}:${PASSWORD}" "https://www.openlearning.com/api/course/status/${COURSE_PATH}" -d "status=offline"
This will return:
{
"success": true,
"status": "offline"
}
List course Administrators
API Method (GET):
https://www.openlearning.com/api/course/admins/<Course Path>
e.g. to list course admins:
curl -f -u "${USERNAME}:${PASSWORD}" "https://www.openlearning.com/api/course/admins/${COURSE_PATH}"
This will return:
{
"admins": [
"example1@email.com",
"example2@email.com"
],
"success": true
}
Add a Course Administrator
API Method (POST):
https://www.openlearning.com/api/course/admins/<Course Path>
POST Parameters:
email_address A string that represents the email address of the user account that will become an administrator of the Course.
e.g. to add a course admin:
curl -f -u "${USERNAME}:${PASSWORD}" "https://www.openlearning.com/api/course/admins/${COURSE_PATH}" -d "email_address=example3@email.com"
This will return:
{
"success": true
}
Change properties of a Class
API Method (POST, GET):
https://www.openlearning.com/api/class/<Class Path>
POST Parameters:
title A string containing the class title (e.g. "First Semester")
type Either:
"open" - anyone can join the class
"requires-activation-code" - only those with an activation code may enrol
"invite-only" - only those invited to join may enrol
"closed" - no-one can join this class yet
isBilled "true" or "false" - depending on whether students need to pay for this class
studentPrice A number, e.g."12.00" which is the price to charge students
currency e.g. "USD" or "AUD"
activationCode A code which users need in order to join the class, e.g. "My Secret Code"
startDate When this class starts, an ISO 8601 date/time string
e.g.
curl -f -u "${USERNAME}:${PASSWORD}" "https://www.openlearning.com/api/class/${CLASS_PATH}" -d "title=First Class" -d "type=open"
This will return a JSON object which looks like:
{
"success": true,
"class": {
"path": "courses/myCourse/Cohorts/FirstClass",
"title": "First Class",
"type": "open"
}
}
List Classes in a Course
API Method (GET):
https://www.openlearning.com/api/course/classes/<Course Path>
This will return:
{
"classes": [
{
"path": "courses/myCourse/Cohorts/FirstClass",
"title": "First Class",
"url": "https://www.openlearning.com/courses/myCourse/Cohorts/FirstClass"
}
],
"success": true
}
List Students in an Institution Portal
API Method (GET):
https://www.openlearning.com/api/institution/enrolments
GET Parameters:
institution - Relative path to institution portal (e.g. myInstitute)
start - The starting position of the list of enrolments (optional and defaults to 0)
end - The end position of the list of enrolments (optional and defaults to 0)
search - text to search for a users name or group (optional and defaults to return all enrolments)
e.g.
curl -XGET -u "${USERNAME}:${PASSWORD}" "https://www.openlearning.com/api/institution/enrolments?institution=myInstitute"
List a Students Enrolments in an Institution Portal
API Method (GET):
https://www.openlearning.com/api/institution/myCourses
GET Parameters:
institution - Relative path to institution portal (e.g. myInstitute)
e.g.
curl -XGET -u "${STUDENT_USERNAME}:${STUDENT_PASSWORD}" "https://www/openlearning.com/api/institution/myCouses?institution=myInstitute"
This will return:
{
"courses": [
{
"name": "course name",
"isOpen": "open",
"url": "https://www.openlearning.com/myInstitute/courses/courseCode",
"isEnrolledIn": true,
"progress": 50, # percentage completed, 0 if isEnrolledIn is false.
"path": "myInstitute/courses/courseCode",
"promoImage": "URL" # URL of the promo image
}
],
"success": true
}
Invite Students into an Institution Portal
API Method (POST):
https://www.openlearning.com/api/institution/invite
POST Parameters:
institution - Relative path to institution portal (e.g. myInstitute)
emailAddressList - A new-line separated list of email addresses. You can specify the user's full name when creating the account (see generateAccount parameter), by placing them after the email address separated by a comma (e.g. Email Address, Full Name). The user can also be added to any institution groups by placing comma separated group names after the Full Name (e.g. Email Address, Full Name, Group 1, Group 2).
generateAccount - true or false flag to specify that a user account will be automatically created and a random password sent to the invited email address. Only institutions with this feature enabled will be able to use this option, otherwise it will ignore this option.
enrollCohorts - A JSON encoded Array of cohort paths that the students will be enrolled in.
This will return:
{
"success": True,
# autoEnrolledStudents represents accounts that already existed, and have been added to the institution
"autoEnrolledStudents": [{
"email": "nowenrolled@student.com",
"user": { ... } # user data
}],
# alreadyEnrolledStudents represents accounts that have already been invited to the institution
"alreadyEnrolledStudents": [{
"email": "enrolled@student.com",
"user": { ... } # user data
}],
# pendingEnrolledEmails are invited, but have not joined the institution yet. The student will need to verify their email address first.
# If generateAccount is true, then these emails now represent new users that have been created.
"pendingEnrolledEmails": ["myemail@example.com"],
# skipped due to being invalid
"unprocessedEmails": ["bademail.com"],
}
e.g.
curl -f -u "${USERNAME}:${PASSWORD}" "https://www.openlearning.com/api/institution/invite" -d "institution=myInstitute" -d "emailAddressList=myemail@example.com"
e.g. with generateAccount and full name
curl -f -u "${USERNAME}:${PASSWORD}" "https://www.openlearning.com/api/institution/invite" -d "institution=myInstitute" -d "emailAddressList=myemail@example.com,Foo Bar" -d "generateAccount=true"
e.g. with generateAccount, full name, and 2 group names
curl -f -u "${USERNAME}:${PASSWORD}" "https://www.openlearning.com/api/institution/invite" -d "institution=myInstitute" -d "emailAddressList=myemail@example.com,Foo Bar,A Group,Group 1" -d "generateAccount=true"
e.g. with enrollCohorts
curl -f -u "${USERNAME}:${PASSWORD}" "https://www.openlearning.com/api/institution/invite" -d "institution=myInstitute" -d "emailAddressList=myemail@example.com" -d 'enrollCohorts=["myInstitute/courses/courseA/cohorts/CohortA","myInstitute/courses/courseB/cohorts/CohortB"]'
Import Student Information for an Institution Portal
API Method (POST):
https://www.openlearning.com/api/institution/importInformation
POST Parameters:
institution - Relative path to institution portal (e.g. myInstitute)
emailAddressList - A new-line separated list of email addresses. You can specify extra info by placing them after the email address separated by commas (e.g. Email Address, Identifier, Username)
e.g.
curl -f -u "${USERNAME}:${PASSWORD}" "https://www.openlearning.com/api/institution/importInformation" -d "institution=myInstitute"& -d "emailAddressList=myemail@example.com"
Invite Students into a Class
API Method (POST):
https://www.openlearning.com/api/class/invite/<Class Path>
POST Parameters:
emailAddressList - A new-line separated list of email addresses.
e.g.
curl -f -u "${USERNAME}:${PASSWORD}" "https://www.openlearning.com/api/class/invite/${CLASS_PATH}" -d "emailAddressList=myemail@example.com"
Sign into OpenLearning from an External Service
via LTI:
OpenLearning accepts LTI authentication (as a POST request) at the following endpoint:
https://www.openlearning.com/lti/<launch path>
Request an LTI connection to be set up for your institution, or course (email support@openlearning.com)
via a URL (link):
https://www.openlearning.com/courseLogin/<Course Path>?signed_request=<Authentication Code>
To generate an authentication code:
- Request an Institution Shared Secret from OpenLearning (email support@openlearning.com). Do not reveal this secret publicly.
- Create a payload of JSON data containing: {"issued_at": 1402643065, "user_id": "user@example.com", "full_name": "Jayne Doe"} (where issued_at is seconds since unix epoch)
- Create an encoded payload by base-64 encoding the JSON data string (this may also use URL-safe encoding which substitutes - instead of + and _ instead of I)
- Generate a SHA-256 HMAC digest of the payload data string and the provided Shared Secret.
- Create an encoded signature by base-64 encoding the HMAC digest.
- Join the encoded signature and the encoded payload with a . (period/full-stop) character.
This will allow the generated (private) link to log the specified user into OpenLearning provided all of the following are satisfied:
- The user is already enrolled in the Cours specified, or the specified email address has been invited to join the course (a new account will be created and the user will be enrolled into this course)
- The user's account is managed by your institution (and existing matching account does not already exist that has had prior activity on OpenLearning)
- The issued_at time is less than a day old
Note: padding ('=' characters) at the end of base64 encoded data are optional and may be omitted.
You can test your HMAC implementation against a reference at (never reveal your actual shared secret):
https://www.openlearning.com/api/login/referenceHMAC/?payload=<JSON Data>&secret=<Secret>
(by default this users url-safe base64 encoding, optionally an encoding=base64 parameter can be passed to use standard base64 encoding)
You can also test that your implementation will authenticate at:
https://www.openlearning.com/api/login/testHMAC/?signed_request=<Signed Request>&secret=<Secret>
(again never reveal you actual secret)
The following is an implementation in Python:
import hmac, hashlib
import time
import base64
import json
def generate_signed_request(shared_secret, user_id, full_name):
payload = {"issued_at": int(time.time()), "user_id": user_id, "full_name": full_name}
encoded_payload = base64.urlsafe_b64encode(json.dumps(payload))
hmac_signature = hmac.new(shared_secret, encoded_payload, hashlib.sha256).digest()
encoded_signature = base64.urlsafe_b64encode(hmac_signature)
signed_request = encoded_signature + '.' + encoded_payload
return signed_request 