Bazaar LMS Interface
This interface is used for adding material to the LMS and viewing material from CMS in the LMS. Bazaar implements licensing and provisioning and gives access to the material. User is never redirected to the CMS, if user has no access to the material.
LMS interface endpoints in this document:
ENDPOINT | METHOD | DESCRIPTION |
---|---|---|
lms/browse | POST | Browse and select material |
lms/view | POST | View material |
Authentication
Authentication to the API occurs via HMAC256 hash token. Hash token is calculated from the JSON payload and your secret key. You can get your client_id and API secret key from the Bazaar administrator.
All API requests must be made over HTTPS. Requests made over plain HTTP will fail.
To make authenticated request to the Bazaar LMS api, you need to generate hash token and put authentication headers to your request.
How to generate Authentication headers:
Authentication = 'BAZAAR' + ' ' + client_id + ':' + calculated hash token
Hash token calculation example(Python 2.7):
import hashlib
import hmac
client_id = "example_client"
message = bytes('''{"first_name":"Teppo","last_name":"Testaaja","email":"Teppo","user_id":123,"context_id":123,"context_title":"DETAILS","role":"student","school":"Koulu","school_id":1235,"city":"Helsinki","city_id":"0123456-7","oid":null,"add_resource_callback_url":"","cancel_callback_url":""}''').encode('utf-8')
secret_key = bytes("bc0ec839034cc0a4fe68af506985ddb52c4cb959").encode('utf-8')
header = "BAZAAR" + ' ' + client_id + ':' + hmac.new(secret_key, message, digestmod=hashlib.sha256).hexdigest();
print(header)
Example output:
$ python test.py
BAZAAR example_client:8a5c839290690a145fc8f128aec4fba0970a004a230fad856d775ea7b528da80
Example authenticated Bazaar LMS request:
POST /api/v1/lms/select HTTP/1.1
Host: bazaar.gov
Date: Mon, 3 Jul 2015 12:00:52 +0300
Authentication: BAZAAR example_client:8a5c839290690a145fc8f128aec4fba0970a004a230fad856d775ea7b528da80
{"first_name":"Teppo","last_name":"Testaaja","email":"Teppo","user_id":123,"context_id":123,"context_title":"DETAILS","role":"student","school":"Koulu","school_id":1235,"city":"Helsinki","city_id":"0123456-7","oid":null,"add_resource_callback_url":"","cancel_callback_url":""}
Possible response codes
HTTP CODE | DESCRIPTION |
---|---|
200 OK | Request was ok. |
400 Bad Request | Invalid parameters. |
401 Unauthorized | Invalid API key. |
Errors
Bazaar uses HTTP response codes to indicate success or failure of an API request. Response code 200 OK
is returned if request was successfull.
Response code in 4xx
range indicates an error.
Same information is also provided in the body: success
value is always returned.
Possible success
values are 0 and 1 indicating failure and success.
Possible human readable error explanation is also returned in error
, if there were error.
Example failed response:
{
"success": 0,
"error" : "Invalid API key."
}
Browse and select material
User browses and selects material from Bazaar to the LMS. LMS must forward user to the returned url within 60 seconds. Returned unique URL will not work after 60 second period from creation.
ENDPOINT | METHOD | DESCRIPTION |
---|---|---|
lms/browse | POST | Browse and select material |
Web sequence diagram:
LMS->Bazaar: browse request
Bazaar->LMS: browse response
LMS-> Bazaar: redirect user to the store
Bazaar->LMS: pass data back to the LMS
Description of the workflow:
- LMS makes a JSON POST request to the Bazaar with arguments using header-based auth.
- Bazaar replies with unique URL.
- LMS forwards user to the URL.
- User selects material from the Bazaar and Bazaar forwards user back to the
add_resource_callback_url
, with material details.
ARGUMENTS for lms/browser request:
Parameter | Description | Type | Required |
---|---|---|---|
first_name | First name of user. | alpha 1-255 | required |
last_name | Last name of user. | alpha 1-255 | required |
Email of user. | optional | ||
user_id | User id from | alpha 1-128 | required |
context_id | Course or page identifier. Must be unique. | alpha 1-128 | required |
context_title | Course or page title | alpha 1-128 | required |
role | Role (enum student, teacher, admin) | enum | required |
school | Name of the school | alpha 1-128 | required |
school_id | School’s identifier in the national level. | alpha 5-10 | required |
city | City’s name | alpha 1-64 | required |
city_id | City’s unique identifier in the national level | alpha 1-10 | required |
oid | User oid | alpha 1-32 | optional |
add_resource_callback_url | LMS callback URL, for adding material to the LMS | url | optional |
cancel_url | Forwarding user back to LMS | url | optional |
Response
Returns JSON object with URL. Browser is redirected to this URL. New URL is always generated.
EXAMPLE REQUEST:
POST /api/v1/lms/browse HTTP/1.1
Host: bazaar.gov
Date: Mon, 3 Jul 2015 12:00:52 +0300
Authentication: BAZAAR example_client:8a5c839290690a145fc8f128aec4fba0970a004a230fad856d775ea7b528da80
{"first_name":"Teppo","last_name":"Testaaja","email":"Teppo","user_id":123,"context_id":123,"context_title":"DETAILS","role":"student","school":"Koulu","school_id":1235,"city":"Helsinki","city_id":"0123456-7","oid":null,"add_resource_callback_url":"","cancel_callback_url":""}
EXAMPLE SUCCESSFUL RESPONSE:
{
"success": 1,
"browse_url": "https:\/\/bazaar.gov\/browse"
}
add_resource_callback_url and cancel_url
LMS must implement add_resource_callback_url
and cancel_url
.
When user selects material from the Bazaar, form is submitted from the Bazaar to the LMS add_resource_callback_url
.
When user cancels adding material, user is forwarded to the url in cancel_url
.
JSON object is BASE64 encoded and included in the hidden element of the form. See example below.
add_resource_callback_url
arguments:
Parameter | Description | Type | Required |
---|---|---|---|
name | Name | alpha 1-128 | required |
description | Descrpition | alpha -2000 | required |
uid | Bazaar resource identified | 128bit UUID | required |
images | thumbnail, standard_resolution and low_resolution images. |
Example payload from the Bazaar to the LMS:
{
"name": "Bazaar Example",
"description": "Long text, Long text, Long text, Long text",
"uid": "dc38da67-bb73-4062-8c67-a6e76e6c8f69",
"images": {
"thumbnail": {
"url": "https:\/\/bazaard.gov\/img\/thumb.jpg",
"width": 150,
"height": 150
},
"standard_resolution": {
"url": "https:\/\/bazaard.gov\/img\/thumb.jpg",
"width": 306,
"height": 306
},
"low_resolution": {
"url": "https:\/\/bazaard.gov\/img\/thumb.jpg",
"width": 612,
"height": 612
}
}
}
Example form
In this example JSON payload is BASE64 encoded and add_resource_callback_url
is https://lms.gov/course/21/add
.
Example form, which is submitted automatically, when material selection is finished and material data is submitted to the LMS:
<form action="https://lms.gov/course/21/add" method="POST">
<input type="hidden" name="params" value="ewogICAgIm5hbWUiOiAiQmF6YWFyIEV4YW1wbGUiLAogICAgImRlc2NyaXB0aW9uIjogIkxvbmcgdGV4dCwgTG9uZyB0ZXh0LCBMb25nIHRleHQsIExvbmcgdGV4dCIsCiAgICAiaW1hZ2VzIjogewogICAgICAgICJ0aHVtYm5haWwiOiB7CiAgICAgICAgICAgICJ1cmwiOiAiaHR0cHM6XC9cL2JhemFhcmQuZ292XC9pbWdcL3RodW1iLmpwZyIsCiAgICAgICAgICAgICJ3aWR0aCI6IDE1MCwKICAgICAgICAgICAgImhlaWdodCI6IDE1MAogICAgICAgIH0sCiAgICAgICAgInN0YW5kYXJkX3Jlc29sdXRpb24iOiB7CiAgICAgICAgICAgICJ1cmwiOiAiaHR0cHM6XC9cL2JhemFhcmQuZ292XC9pbWdcL3RodW1iLmpwZyIsCiAgICAgICAgICAgICJ3aWR0aCI6IDMwNiwKICAgICAgICAgICAgImhlaWdodCI6IDMwNgogICAgICAgIH0sCiAgICAgICAgImxvd19yZXNvbHV0aW9uIjogewogICAgICAgICAgICAidXJsIjogImh0dHBzOlwvXC9iYXphYXJkLmdvdlwvaW1nXC90aHVtYi5qcGciLAogICAgICAgICAgICAid2lkdGgiOiA2MTIsCiAgICAgICAgICAgICJoZWlnaHQiOiA2MTIKICAgICAgICB9CiAgICB9LAogICAgInVpZCI6ICJkYzM4ZGE2Ny1iYjczLTQwNjItOGM2Ny1hNmU3NmU2YzhmNjkiCn0=">
</form>
LMS must then BASE64 decode params from the params field to get the JSON payload described.
Example of decoding BASE64 encoded JSON:
import base64
import json
params = '''ewogICAgIm5hbWUiOiAiQmF6YWFyIEV4YW1wbGUiLAogICAgImRlc2NyaXB0aW9uIjogIkxvbmcgdGV4dCwgTG9uZyB0ZXh0LCBMb25nIHRleHQsIExvbmcgdGV4dCIsCiAgICAiaW1hZ2VzIjogewogICAgICAgICJ0aHVtYm5haWwiOiB7CiAgICAgICAgICAgICJ1cmwiOiAiaHR0cHM6XC9cL2JhemFhcmQuZ292XC9pbWdcL3RodW1iLmpwZyIsCiAgICAgICAgICAgICJ3aWR0aCI6IDE1MCwKICAgICAgICAgICAgImhlaWdodCI6IDE1MAogICAgICAgIH0sCiAgICAgICAgInN0YW5kYXJkX3Jlc29sdXRpb24iOiB7CiAgICAgICAgICAgICJ1cmwiOiAiaHR0cHM6XC9cL2JhemFhcmQuZ292XC9pbWdcL3RodW1iLmpwZyIsCiAgICAgICAgICAgICJ3aWR0aCI6IDMwNiwKICAgICAgICAgICAgImhlaWdodCI6IDMwNgogICAgICAgIH0sCiAgICAgICAgImxvd19yZXNvbHV0aW9uIjogewogICAgICAgICAgICAidXJsIjogImh0dHBzOlwvXC9iYXphYXJkLmdvdlwvaW1nXC90aHVtYi5qcGciLAogICAgICAgICAgICAid2lkdGgiOiA2MTIsCiAgICAgICAgICAgICJoZWlnaHQiOiA2MTIKICAgICAgICB9CiAgICB9LAogICAgInVpZCI6ICJkYzM4ZGE2Ny1iYjczLTQwNjItOGM2Ny1hNmU3NmU2YzhmNjkiCn0='''
payload = base64.b64decode(params)
print json.dumps( json.loads(payload))
Output:
$ python decode.py
{"images": {"low_resolution": {"url": "https://bazaard.gov/img/thumb.jpg", "width": 612, "height": 612}, "thumbnail": {"url": "https://bazaard.gov/img/thumb.jpg", "width": 150, "height": 150}, "standard_resolution": {"url": "https://bazaard.gov/img/thumb.jpg", "width": 306, "height": 306}}, "uid": "dc38da67-bb73-4062-8c67-a6e76e6c8f69", "name": "Bazaar Example", "description": "Long text, Long text, Long text, Long text"}
Viewing material
Person views selected material. LMS must always make a new view request when users wants to view material. LMS must forward user to the returned url within 60 seconds. Returned unique URL will not work after 60 second period from creation.
ENDPOINT | METHOD | DESCRIPTION |
---|---|---|
lms/view | POST | View material. |
Web sequence diagram:
participant LMS
participant Bazaar
participant CMS
LMS->Bazaar: open request
Bazaar->LMS: open response
LMS->Bazaar: open unique url
Bazaar->CMS: forward to CMS endpoint
Description
- LMS makes a JSON POST request to the Bazaar with arguments for lms/view using header-based authentication.
- Bazaar replies with unique url and LMS forwards user to the unique url.
- Bazaar forwards user to the selected material with unique token.
- LMS gets users user data from the Bazaar using token.
Arguments for lms/view
Parameter | Description | Type | Required |
---|---|---|---|
first_name | First name of user. | alpha 1-255 | required |
last_name | Last name of user. | alpha 1-255 | required |
Email of user. | optional | ||
user_id | User id from LMS | alpha 1-255 | required |
context_id | Course or page identifier. Must be unique. | alpha 1-128 | required |
context_title | Course or page title | alpha 1-128 | required |
role | Role (enum student, teacher, admin) | enum | required |
school | Name of the school | alpha 1-128 | required |
school_id | School’s identifier in the national level. | alpha 5-10 | required |
city | City’s name | alpha 1-64 | required |
city_id | City’s unique identifier in the national level | alpha 1-10 | required |
oid | User oid | alpha 1-32 | optional |
resource_uid | Resource Bazaar UUID | 128bit UUID | required |
return_url | Forwarding user back to the LMS | url | optional |
Example request:
POST lms/view HTTP/1.1
Host: bazaar.gov
Date: Mon, 3 Jul 2015 12:00:52 +0300
Authentication: BAZAAR example_client:8a5c839290690a145fc8f128aec4fba0970a004a230fad856d775ea7b528da80
{
"first_name": "Teppo",
"last_name": "Testaaja",
"email": "Teppo",
"user_id": 123,
"context_id": 123,
"context_title": "DETAILS",
"role": "student",
"school": "Koulu",
"school_id": 1235,
"city": "Helsinki",
"city_id": "0123456-7",
"oid": null,
"resource_uid": "dc38da67-bb73-4062-8c67-a6e76e6c8f69",
"return_url": "https:\/\/lms.gov\/"
}
Example response:
{
"success": 1,
"view_url": "https:\/\/bazaar.gov\/df0ae5a63ab170f69706301d4d5b0356a0e800108b9e2fed26e36116b88cce28"
}