Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Initial Edustore version #3

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Initial Edustore version #3

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7a12a42
Initial Edustore version
pkarppi Sep 1, 2015
b910e1f
Some minor changes about encoding and naming.
pkarppi Sep 17, 2015
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
230 changes: 224 additions & 6 deletions bazaar/interface.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,230 @@

Bazaar Interfaces
*****************
Bazaar API
=========================

LMS
===
draft v0.2

.. contents::

CMS
===

JSON
====

JSON Character encoding is always UTF-8.

Signing and Authentication
==========================

There are two authencation types:

1. Header HMAC256 AUTH token in headers and JSON body (Similar: http://docs.aws.amazon.com/AmazonS3/latest/dev/RESTAuthentication.html)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should be written here how the token is calculated and where it is acquired. Example how the call is made with curl from CLI would be nice. What does "and JSON body" means?


JSON body is encoded using UTF-8.

Example authenticated Edustore request::

POST /api/v1/cms/browse HTTP/1.1
Host: bazaar.gov
Date: Mon, 3 Jul 2015 12:00:52 +0300
Authentication: EDUSTORE CLIENTID:d8a928b2043db77e340b523547bf16cb4aa483f0645fe0a290ed1f20aab76257

{"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":""}

2. GET request with params=<json>&authentication=<EDUSTORE client_id:hash>

JSON is encoded using https://www.ietf.org/rfc/rfc4627.txt. All parameters are urlencoded.

Example forwarding GET request::

GET /cms/api/?params=%7B%22first_name%22%3A%22Teppo%22%2C%22last_name%22%3A%22Testaaja%22%2C%22email%22%3A%22Teppo%22%2C%22user_id%22%3A123%2C%22context_i d%22%3A123%2C%22context_title%22%3A%22DETAILS%22%2C%22role%22%3A%22student%22%2C%22school%22%3A%22Koulu%22%2C%22school_id%22%3A1235%2C%22city%22%3A%22Helsinki%22%2 C%22city_id%22%3A%220123456-7%22%2C%22resource_uid%22%3A%22123-123-13-123%22%2C%22return_url%22%3A%22https%3A%5C%2F%5C%2Flms.gov%5C%2F%22%2C%22created%22%3A%222015 -9-17T15%3A46%3A04%2B03%3A00%22%7D&authentication=EDUSTORE+CLIENTID%3Ad8a928b2043db77e340b523547bf16cb4aa483f0645fe0a290ed1f20aab76257 HTTP/1.1
Host: publisher.com
Date: Mon, 3 Jul 2015 12:00:52 +0300



1 Adding material
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In already defined terms this is the Bazaar CMS Interface?

==============================


1.1 Searching and adding material to the LMS
--------------------------------------------

Learning material can be added with three use methods:

1. User open Bazaar repository directly.
2. | User select materials from the Bazaar repository to the LMS by using:
| - Drag and Drop
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The term "drag and drop" is not defined anywhere in this document. What does it mean, where it is used and who is using it? I assume it means in the web page and by the end user, and that they are dragging a link on top of some element in some page somewhere. This needs more info how that should be implemented. Also, "Window to window" is not clear what it means related to "drag and drop".

| - Window to window
| NOTE: These material selection methods cannot be used from mobile devices (Windows Phone, iOS, Android).
3. User selects material from integrated embedded Bazaar JS module, which can be included to any LMS. This method uses drag and drop.


API workflow for selecting material from Bazaar directly:

1. LMS makes a JSON POST request to the Bazaar with params from table 1, using header-based auth.
2. Bazaar replies with unique URL and LMS forwards user to the unique url.
3. User selects learning material from the Bazaar and Bazaar forwards user back to the add_resource_callback_url, with resource details(ie. name, description).

Params table 1:

========================== ================================================ ============ =========
Param Description Type Required
========================== ================================================ ============ =========
first_name First name of user. alpha 1-255 required
last_name Last name of user. alpha 1-255 required
email Email of user. email 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
========================== ================================================ ============ =========



1.1 Material drag and drop
--------------------------

LMS should implement drop functionality directly and parse links with "Bazaar.fi/<base64 encoded json>.
Base64 encoded JSON has basic information about the resource: name, description and uid.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing information about the JSON document structure and encoding. I can again assume it is a dict, keys and values are UTF-8 and the fields are always the same and only these three: name, description and uid. But what does them mean? What is name? How long can it be? Same for description? Can it be unlimited in length? What is uid and is it integer. If it is integer can it be negative? Or is it a string? And how long can it be?



2 Viewing material
===================

Use case:
Person wants to view selected material/resource.

API workflow:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same comments apply here as above.


1. LMS makes a JSON POST request to the Bazaar with params from table 2, using header-based auth.
2. Bazaar replies with unique url and LMS forwards user to the unique url.
3. User is forwarded to the the publisher system. Publisher should implement 2.2 part of the specs.


2.1 LMS to Bazaar
--------------------

Workflow:

1. LMS makes a JSON POST request to the Bazaar with params from table 2, using header-base authentication.
2. Bazaar replies with unique url and LMS forwards user to the unique url.
3. Bazaar displays or forwards user to the selected material.

Bazaar does all the license and logging functionality.

Params table 2(Bazaar CMS Interface):

========================== ================================================ ============ =========
Param Description Type Required
========================== ================================================ ============ =========
first_name First name of user. alpha 1-255 required
last_name Last name of user. alpha 1-255 required
email Email of user. email 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 UID 128bit UID required
return_url Forwarding user back to the LMS url optional
========================== ================================================ ============ =========


2.2 Bazaar to CMS
-------------------

Bazaar forwards user to the publisher CMS system after authentication and license checking is done.

Use case:
Forwarding user from Bazaar to the CMS.

API workflow:
1. Bazaar generates json payload with params from table 3, using GET authentication.
2. Bazaar forwards user to the publisher viewing API with

Params table 3: Bazaar CMS Viewing API parameters

========================== ================================================================================== ============ ========
Param Description Type Required
========================== ================================================================================== ============ ========
first_name First name of user. alpha 1-255 required
last_name Last name of user. alpha 1-255 required
email Email of user. email optional
user_id Bazaar user id bigint required
context_id Bazaar unique context id bigint 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 1-12 required
city City's name alpha 1-64 required
city_id City's unique identifier at the national level alpha 5-10 required
oid OID https://confluence.csc.fi/download/attachments/8127300/Oppijanumero+ja+OID.pdf alpha 1-32 required
resource_uid Bazaar resource uid 128bit UID required
publisher_material_id Bazaar publisher unique identifier alpha 1-128 required
resource_url Bazaar resource url url required
demo_mode demo mode (0, 1) int required
preview preview mode(0, 1) int required
return_url url for forwarding user back to LMS url required
token_date When the token was generated. Datetime in GMT time. Datetime format is ISO 8601. datetime required
========================== ================================================================================== ============ ========




3 Central Learning Record Store
================================

3.1 xAPI
--------



@TODO




3 Bazaar CMS API
==================

@TODO

4 Logging API
=============

@TODO


5 License API
=============

@TODO


Glossary of Terms
=================

@TODO

API = Application Programming Interface

URL = Uniform Resource Identifier

LMS = Learning Management System

CMS = Content Management System

JSON = JavaScript Object Notation

JS = JavaScript