-
Notifications
You must be signed in to change notification settings - Fork 1
LOEP Session Token API
The LOEP Session Token API is a REST API that allows third-party applications to generate session tokens that can be later used for different actions such as embedding evaluation web forms and showing results of evaluations through charts. This documentation belongs to the version 1.0 of the API.
The LOEP Session Token API uses HTTP basic authentication (which can be used over HTTP or HTTPs).
The credentials to be included in the HTTP Authentication Header should be: the name of the application as registered in LOEP, and the authentication token provided by LOEP for such application.
An authenticated application only has permissions to access data of their own Learning Objects (i.e. the Learning Objects that it has registered).
The endpoint of the LOEP Session Token API in a LOEP instance is:
http(s)://domain/api/v1/session_token
All reponses are provided in JSON format.
The following table summarizes the methods offered by the API:
| Request | Description |
|---|---|
| GET /api/v1/session_token | Returns a new session token for the application. The data for the session token can be provided in the "session_token" parameter (see table 'Session Token Data'). |
| POST /api/v1/session_token | Returns a new session token for the application. The data for the session token can be provided in the "session_token" parameter (see table 'Session Token Data'). |
| POST /api/v1/session_token/current | Returns the latest active session token of the application. If there are no active session tokens, a new one is created. |
All fields are optional.
| Field | Description |
|---|---|
| action | The action for which the session token is requested. Possible values: "all", "evaluate", and "showchart". Default value is "all". The "evaluate" action allows to perform an evaluation of a Learning Object. The "showchart" action allows to display the results of the evaluations of a Learning Object through charts. The "all" action allows to perform any of the above actions. |
| repository | Name of the application (as registered in LOEP) that requests the session token. |
| lo_id_repository | Identifier within the application of the Learning Object over which the action (evaluate/showchart) can be performed. For instance, if action is "evaluate" and the lo_id_repository field is provided, the session token will only allow to evaluate the Learning Object with such identifier. |
| evmethod_name | Name of the evaluation model for which the action is allowed. For instance, if action is "evaluate" and evmethod_name is wblts, the session token will only allow to perform evaluations according to the WBLT-S evaluation model. This field can be combined with the lo_id_repository field. |
| permanent | If true, the session token will never expire. Default value is false. |
| hours | If the session token is not permanent, hours is the number of hours that the session token will remain active before it expires. Default value is 12. |
| multiple | If true, the session token can be used to perform multiple evaluations. Otherwise, the session token will be invalidated after its first use. Default value is false. |
This action enables an application registered in LOEP to embed in its website a web form to allow end users to evaluate Learning Objects. For that, the application should include an <iframe> with a URL with the following structure:
http(s)://domain/evaluations/evMethod/embed
Where the value of evMethod is one of the following:
| Evaluation Model | evMethod |
|---|---|
| "LORI v1.5" | loris |
| "LOEM" | loems |
| "WBLT-S" | wbltses |
| "WBLT-T" | wbltts |
| "SUS" | suses |
Automatic evaluation models cannot be embedded since they do not have web forms, and they are not intended to be used by human users.
A set of parameters need to be included in the http(s)://domain/evaluations/evMethod/embed URL. Besides, some optional parameters can be added.
| Param | Description |
|---|---|
| session_token | The session token obtained by the application through the LOEP Session Token API. This field is mandatory. |
| app_name | Name of the application that generated the session token as registered in LOEP. This field is mandatory. |
| repository | Name of the repository to which the Learning Object belongs as indicated in LOEP. This field is mandatory. |
| lo_id | The identifier of the Learning Object for which the evaluation form is requested. If the param "use_id_loep" is included (with any value), lo_id should be the id of the Learning Object in LOEP. Otherwise, lo_id should be the id of the Learning Object within the application. This field is mandatory. |
| id_user_app | Identifier of the user within the application (only for logged users). |
| ajax | If true, the evaluation will be sent through AJAX. |
| locale | The language in which the web form of the evaluation will be provided. Possible values: "en" and "es". |
This action enables an application registered in LOEP to embed in its website different charts to display the results of the evaluations of the Learning Objects. For that, the application should include an <iframe> with a URL with the following structure:
http(s)://domain/los/loId/representation
Where loId should be the identifier of the Learning Object within the application. If the param "use_id_loep" is included (with any value), lo_id should be the id of the Learning Object in LOEP.
A set of parameters need to be included in the http(s)://domain/los/loId/representation URL. Besides, some optional parameters can be added.
| Param | Description |
|---|---|
| session_token | The session token obtained by the application through the LOEP Session Token API. This field is mandatory. |
| app_name | Name of the application that generated the session token as registered in LOEP. This field is mandatory. |
| repository | Name of the repository to which the Learning Object belongs as indicated in LOEP. This field is mandatory. |
| evmethods | A list separated by commas of the evaluation models for which the graphs of results should be provided. The names of the evaluation models should be provided according to the table shown below. This field is mandatory. |
| locale | The language in which the charts will be provided. Possible values: "en" and "es". |
| Evaluation Model | Value in the evmethods field |
|---|---|
| "LORI v1.5" | lori |
| "LOEM" | loem |
| "WBLT-S" | wblts |
| "WBLT-T" | wblt |
| "SUS" | sus |
| "Metadata Quality" | metadata |
| "Interaction Quality" | qinteraction |
LOEP provides a JavaScript API that can by used by third-party web client applications to request session tokens to an application registered in LOEP and used these tokens to perform all possible actions: "evaluate" and "showchart".
The JavaScript API can be downloaded from https://github.com/ging/vish/blob/master/vendor/assets/javascript/loep.js.
LOEP also provides a Ruby API that can by used by third-party server applications to request session tokens to a LOEP instance through the LOEP Session Token API.
This API can be found at: https://github.com/ging/vish/blob/master/app/models/loep.rb.
An example of how to implement an token provider in a Ruby on Rails application using this Ruby API can be found at: https://github.com/ging/vish/blob/master/app/controllers/loep/session_token_controller.rb.