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.

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

Initial Edustore version #3

Open
wants to merge 2 commits into
base: master
from
Open

Conversation

@pkarppi
Copy link
Contributor

@pkarppi pkarppi commented Sep 1, 2015

Initial Edustore version.

@derega
Copy link
Member

@derega derega commented Sep 9, 2015

Nice to see our first contribution to the documentation from outside ECA personnel :)

Few notes, though.

The documentation should be written in a language which is neutral. It should not have any mention of product names, companies, or proprietary tools, protocols, services or products.

All information in the documentation should be written so that it can be used to implement the service or interface. If there are mentions of software or code that needs to be open and licensed with ECA compatible license.

The primary readers of this documentation are service providers who are implementing their own Bazaar. The LMS and CMS implementers are secondary, but are also using this documentation.

Reference implementation in the form of source code would be preferred to prove that the interface documentation in this repository is possible to implement in a production system. ECA has defined that it would be best if everything in the documentation is backed by open and free reference implementation.

There are more comments inline in the commit. There are a lot of them mainly because there are no examples and reference implementation of the interface. The specification must be pretty precise so that different services know how to implement it the same way.

We've been using https://www.websequencediagrams.com/ service to create sequence diagrams before. It renders the diagram as PNG from a text representation. The text can be committed to the repository and it is understandable as is. This way we are not bound to any proprietary tool to generate diagrams. Also it's fun to create those :)

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


2.2 Edustore to CMS

This comment has been minimized.

@derega

derega Sep 9, 2015
Member

Already defined term for this is the Bazaar CMS Interface.

2. Edustore replies with unique url and LMS forwards user to the unique url.
3. Edustore displays or forwards user to the selected material.

Edustore does all the license and logging functionality.

This comment has been minimized.

@derega

derega Sep 9, 2015
Member

This is specific to the implementation you guys have, not what might be in some other service implementing this API. This kind of language should be in the Bazaar general explanation page, not in this document.


Workflow:

1. LMS makes a JSON POST request to the Edustore with params from table 2, using header-base authentication.

This comment has been minimized.

@derega

derega Sep 9, 2015
Member

Same comments as above. Actually those JSON document structures and encoding information should be places in the beginning of the document and then just refer to them here.

3. User is forwarded to the resource(if resource is internal pdf, videos, epub, scorms) or forwarded to the publisher system. Publisher should implement 2.2 part of the specs.


Edustore integrated player?

This comment has been minimized.

@derega

derega Sep 9, 2015
Member

How is this integrated player defined and implemented? Is it part of this API specification? Should it be?


1. LMS makes a JSON POST request to the Edustore with params from table 2, using header-based auth.
2. Edustore replies with unique url and LMS forwards user to the unique url.
3. User is forwarded to the resource(if resource is internal pdf, videos, epub, scorms) or forwarded to the publisher system. Publisher should implement 2.2 part of the specs.

This comment has been minimized.

@derega

derega Sep 9, 2015
Member

What does "internal" here means and how this should be implemented?


API workflow:

1. LMS makes a JSON POST request to the Edustore with params from table 2, using header-based auth.

This comment has been minimized.

@derega

derega Sep 9, 2015
Member

It says here that only header-based auth is supported, but at the top of the document two auth methods are introduced.

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

API workflow:

This comment has been minimized.

@derega

derega Sep 9, 2015
Member

Same comments apply here as above.

--------------------------

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

This comment has been minimized.

@derega

derega Sep 9, 2015
Member

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?


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

This comment has been minimized.

@derega

derega Sep 9, 2015
Member

Again, missing specification of the request and response data and encoding.

API workflow for selecting material from Edustore directly:

1. LMS makes a JSON POST request to the Edustore with params from table 1, using header-based auth.
2. Edustore replies with unique URL and LMS forwards user to the unique url.

This comment has been minimized.

@derega

derega Sep 9, 2015
Member

Specification of the reply is missing. I assume it comes in the body of the response, but how it is encoded? I assume UTF-8 again, but is it inside JSON document like the request was?


API workflow for selecting material from Edustore directly:

1. LMS makes a JSON POST request to the Edustore with params from table 1, using header-based auth.

This comment has been minimized.

@derega

derega Sep 9, 2015
Member

There should be specification of the data structure how these parameters are delivered. I can assume from the information in this document that it is a JSON dict which is put to the URL in "?params=" but should the JSON be encoded somehow? Which encoding is used in the content, I assume UTF-8 but cannot be sure, and I assume urlencoding is used but cannot be sure.

| - 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 Edustore JS module, which can be included to any LMS. This method uses drag and drop.

This comment has been minimized.

@derega

derega Sep 9, 2015
Member

Where can I obtain this JS module? Is is part of this API specification? Or are there reference implementation somewhere which can be used to build the production version? Should this be part of the API specification as it sounds like it is implementation specific to services which are implementing this API.


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

This comment has been minimized.

@derega

derega Sep 9, 2015
Member

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".


Learning material can be added with three use methods:

1. User open Edustore repository directly.

This comment has been minimized.

@derega

derega Sep 9, 2015
Member

Where this is and how it is implemented related to this API? How this can be implemented from this description. Be more specific.

1. Header HMAC256 AUTH token in headers and JSON body (Similar: http://docs.aws.amazon.com/AmazonS3/latest/dev/RESTAuthentication.html)
2. GET/POST request with params=<json>&authentication=<client_id:hash>

1 Adding material

This comment has been minimized.

@derega

derega Sep 9, 2015
Member

In already defined terms this is the Bazaar CMS Interface?

There are two supported methods:

1. Header HMAC256 AUTH token in headers and JSON body (Similar: http://docs.aws.amazon.com/AmazonS3/latest/dev/RESTAuthentication.html)
2. GET/POST request with params=<json>&authentication=<client_id:hash>

This comment has been minimized.

@derega

derega Sep 9, 2015
Member

More than one line description of the usage of parameters would be nice. This is now more than confusing to the reader what this means. When is GET and POST used? Explanation what is "params" and "authentication". What does "client_id:hash" mean? Is it one value or two? Should it be "<client_id>:"?


There are two supported methods:

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

This comment has been minimized.

@derega

derega Sep 9, 2015
Member

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?

@@ -1,12 +1,207 @@

Bazaar Interfaces
*****************
Edustore Distributed API

This comment has been minimized.

@derega

derega Sep 9, 2015
Member

We should use the term Bazaar here as it is defined elsewhere to describe the service which handles material transfer, commerce and licensing. Also "Edustore" is product name of one company.

@derega
Copy link
Member

@derega derega commented Sep 9, 2015

Whoops! Those inline comments came here in the wrong order. Sorry :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

2 participants
You can’t perform that action at this time.