Bazaar CMS Interface
This interface is used for adding material to the Bazaar and viewing material through the Bazaar. There is also one endpoint for viewing material.
CMS interface endpoints in this document:
ENDPOINT | METHOD | DESCRIPTION |
---|---|---|
cms/materials | GET | Returns your materials |
cms/materials | POST | Create a material |
cms/materials/<uid> | PUT | Update a material |
cms/materials/<uid> | GET | Get material |
cms/materials<uid> | DELETE | Delete material |
cms/metadata | GET | Return all available metedata that can be added to the material. |
cms/products | POST | Create a product. |
cms/products/<uid> | PUT | Update product information. |
cms/products/<uid> | GET | Get product information |
cms/validate/<token> | GET | For viewing material. Get and validate view token. Returns user and resource data. |
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.
Form of 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 = "CMS" + ' ' + client_id + ':' + hmac.new(secret_key, message, digestmod=hashlib.sha256).hexdigest();
print(header)
Example output:
$ python test.py
CMS example_client:8a5c839290690a145fc8f128aec4fba0970a004a230fad856d775ea7b528da80
Example authenticated Bazaar LMS request:
GET cms/token HTTP/1.1
Host: bazaar.gov
Date: Mon, 3 Jul 2015 12:00:52 +0300
Authentication: CMS 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. |
Metadata and tags
Metadata is built up by country, so first part of the metadata item always indicates country.
Metadata might have translations in other languages in some countries, but you can also use translated metadata.
Use metadata
endpoints to receive all available metadatas or parts of it.
Metadata is a hierarchical data structure where each level is delimited with /
character.
Tags are extra information about the material and you can create them as you wish.
Get metadata
Metadata is flat map of pre-defined metadata. There is also namespace global for global metadata mapping. Normally it is more user friendly to use country specific metadata, but if your material is designed to work globally, you can also use global metadatas.
ENDPOINT | METHOD | DESCRIPTION |
---|---|---|
cms/metadata | GET | Returns all available metadata. |
cms/metadata/<country> | GET | Returns all available metadata by country |
REQUEST:
GET cms/metadata HTTP/1.1
Host: bazaar.gov
Date: Mon, 3 Jul 2015 12:00:52 +0300
Authentication: CMS example_client:8a5c839290690a145fc8f128aec4fba0970a004a230fad856d775ea7b528da80
RESPONSE:
{
"success" : 1,
"data" : [
"fi/Kouluaste/1.luokka",
"fi/Kouluaste/2.luokka",
"fi/Kouluaste/3.luokka",
"fi/Kouluaste/4.luokka",
"fi/Kouluaste/5.luokka",
"fi/Kouluaste/6.luokka",
"fi/Kouluaste/7.luokka",
"fi/Kouluaste/7.luokka",
"global/Subject/Biology"
]
}
Create, read, update and delete material
You can create, read, update and delete your material with these actions.
CRUD operation endpoints:
ENDPOINT | METHOD | DESCRIPTION |
---|---|---|
cms/materials | GET | Return materials |
cms/materials | POST | Create material |
cms/materials/<uid> | PUT | Update material |
cms/materials/<uid> | GET | Get material |
cms/materials/<uid> | DELETE | Delete material |
Material params table:
PARAMS | DESCRIPTION | |
---|---|---|
name | required | Name (max. 255 chars) |
description | required | Description (max. 2048 chars) |
language | required | Material language |
publisher_resource_id | required,unique | Publisher unique material id (in your system) |
publisher_data | Publisher additional data | |
metadata | Metadata in array format. Max 32 items. You must first get available metadatas with cms/metadata. | |
tags | Material tags max 32 items. Max length of a tag is 64. | |
images | Assoc array of images. See example. |
publisher_resource_id must be unique in your CMS, so you cannot have multiple materials with the same id.
Example material
Example material data:
{
"name": "Bazaar example",
"active" : 0,
"description": "Bazaar example material.",
"language" : "fi-FI",
"publisher_resource_id" : "123123123"
"publisher_data" : "custom payload",
"metadata": [
"fi/Luokka-aste/1. Luokka",
"fi/Luokka-aste/2. Luokka",
"fi/Luokka-aste/3. Luokka",
"fi/Oppiaine/Biologia",
],
"tags" : ["Tag 1", "Tags 2"],
"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
}
}
}
Get materials
Returns material stored in Bazaar. API returns max. 100 items at time. You can use pagination to get more sequential data. Call URL in the next_URL param to get next set of data.
ENDPOINT | METHOD | DESCRIPTION |
---|---|---|
cms/materials | GET | Return materials |
REQUEST:
GET cms/materials HTTP/1.1
Host: bazaar.gov
Date: Mon, 3 Jul 2015 12:00:52 +0300
Authentication: CMS example_client:8a5c839290690a145fc8f128aec4fba0970a004a230fad856d775ea7b528da80
RESPONSE:
{
"count": 1
"data": [{
"name": "Bazaar example",
"description": "Bazaar example material.",
"language": "fi-FI",
"publisher_resource_id": "123123123"
"publisher_url": "https:\/\/",
"metadata": [
"Kouluaste/1. Luokka",
"Kouluaste/2. Luokka",
"Kouluaste/2. Luokka",
"Oppiaine/Biologia",
],
"tags": ['Tag 1', 'Tags 2'],
"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
}
}
}],
"pagination": {
"next_url": "cms/materials?start=100",
}
}
Create material
To create a resource make following request:
REQUEST:
POST cms/materials HTTP/1.1
Host: bazaar.gov
Date: Mon, 3 Jul 2015 12:00:52 +0300
Authentication: CMS example_client:8a5c839290690a145fc8f128aec4fba0970a004a230fad856d775ea7b528da80
{
"name": "Bazaar example",
"description": "Bazaar example material.",
"language": "fi-FI",
"publisher_resource_id": "123123123"
"publisher_url": "https:\/\/",
"metadata": [
"fi/Kouluaste/1. Luokka.",
"fi/Kouluaste/2. Luokka.",
"fi/Kouluaste/2. Luokka.",
],
"tags": ['Asiasana', 'Asiasana2'],
"images": {
"thumbnail": {
"url": "https:\/\/bazaar.gov\/img\/thumb.jpg",
"width": 150,
"height": 150
},
"standard_resolution": {
"url": "https:\/\/bazaar.gov\/img\/thumb.jpg",
"width": 306,
"height": 306
},
"low_resolution": {
"url": "https:\/\/bazaar.gov\/img\/thumb.jpg",
"width": 612,
"height": 612
}
}
}
RESPONSE:
{
"success": 1
"resource_uid": "eb5b7565-a3b9-487a-92ef-ed6f86976299"
}
Viewing material
User is redirected to your CMS with unique Bazaar token.
You must validate Bazaar view token from Bazaar with cms/validate/<token>
Rest API call.
One token can only be validated once. The API returns 401 Unauthorized
if the token is expired.
ENDPOINT | METHOD | DESCRIPTION |
---|---|---|
cms/validate/<token> | GET | For viewing material. Get and validate view token. Returns user and resource data. |
Token timeout example response
Bazaar has 1 minute timeout from the creation of the token.
TIMEOUT RESPONSE:
{
"success" : 0,
"error" : 401,
"error_message" : "Token timeout"
}
USED TOKEN RESPONSE:
{
"success" : 0,
"error" : 401,
"error_message" : "Token already used"
}
REQUEST:
GET cms/validate/2602d8eca94a206db5e6f7cf3c6768fb3c330f26fb25ee00bbd5cc72d5c35ecd HTTP/1.1
Host: bazaar.gov
Date: Mon, 3 Jul 2015 12:00:52 +0300
Authentication: CMS example_client:8a5c839290690a145fc8f128aec4fba0970a004a230fad856d775ea7b528da80
RESPONSE:
{
"success" : 1,
"data": {
"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,
"country" : "FI",
"language" : "fi",
"instance_id" : "3eef7414-268e-4be7-a1d8-6f5809859c63",
"bazaar_user_id" : "79f6ad94-126e-436f-9e66-b9ca9d84abc5",
"bazaar_context_id" : "9d1a6415-5f76-41bf-853e-f1eb824518af",
"lsr_store" : "https//bazaar.gov/",
"publisher_material_id" : "A1"
"resource_uid" : "7d59be29-0e76-472e-a26d-339606a2b20f",
"resource_url" : "",
"organization_name" : "Testikoulu",
"organization_id": "c3552524-a864-44ee-8e77-52d728281935",
"history_id" : "444735e09f0606de0d9f976d81594b1ae8c2e9386f00410c18e213d97a395937",
"demo" : 0,
"chargeable" : 0
}
}
Params from the Bazaar:
PARAM | DESCRIPTION |
---|---|
first_name | First name of the user. |
last_name | Last name of the user. |
Email of the user. | |
user_id | User id from the LMS. |
context_id | Context id from the LMS. |
context_title | Context title from the LMS. |
role | User role. admin, teacher or student |
school | School’s name. |
school_id | School id |
city | City name |
city_id | City ID |
oid | Student ID |
country | Country code(ISO 3166-1 alpha-2) |
language | Language code (ISO 639-1) |
instance_id | Globally uniqe instance ID from the Bazaar. |
bazaar_user_id | Globally unique Bazaar user ID |
bazaar_context_id | Globally unique Bazaar context ID |
resource_uid | Bazaar resource ID |
publisher_material_id | CMS material link #1 |
resource_url | CMS material link #2 |
organization_name | User organization nanme |
organization_id | User organization ID in the Bazaard |
history_id | Unique history ID of this transaction |