EuropeanaRS API JavaScript library

EuropeanaRS API JavaScript library (1.0)

1. Introduction
2. Getting Started
   1. Download
   2. Initialize the library
   3. Build the data for the API call
   4. Call the API
3. API Methods
4. Examples

Introduction

EuropeanaRS API JavaScript library is a lightweight JavaScript library provided to facilitate third-party web applications the usage of the EuropeanaRS API, which allows performing cross-domain requests of Learning Object recommendations based on contextual information, user profiles and customized settings.
This documentation belongs to the version 1.0 of the EuropeanaRS API JavaScript library.

Getting started

1. Import the JavaScript library

The javascript library is available at https://github.com/agordillo/EuropeanaRS/blob/master/extras/europeanars_v1.js. We recommend to download it and import it in your html page from a local file:

<script src="/js/europeanars_v1.js"></script>

Besides, jQuery 1.5+ is required. So, we have to import it as well.

2. Initialize the library

Then we have to initialize the library calling the init method, and providing the API_KEY (i.e. public key) and PRIVATE_KEY of our application, and the API_URL (i.e. the API endpoint of the EuropeanaRS instance we want to use).

<script type="text/javascript">
  EuropeanaRS_API.init({debug: false, API_KEY: "demonstration", PRIVATE_KEY: "demonstration", API_URL: "http://localhost:3000/api/"});
</script>

3. Build the data for the API call

Before calling the API for requesting recommendations, we should build the data.

    var data = {};
    data["n"] = 20; //Request 20 Learning Objects (LOs)

    //Request Learning Objects similar to the following:
    data["lo_profile"] = {};
    data["lo_profile"]["resource_type"] = "TEXT";
    data["lo_profile"]["title"] = "South Wales daily news - 1895-07-30";

    //Personalize the recommendations for the following user:
    data["user_profile"] = {};
    data["user_profile"]["language"] = "en";
    var liked_los = [...];
    data["user_profile"]["los"] = JSON.stringify(liked_los);

    //Use the following settings for the system:
    data["settings"] = {};

    data["settings"]["preselection_size"] = 300;
    data["settings"]["preselection_filter_languages"] = "false";

    //Specify general weights
    //The sum of all weights must be 1. Otherwise can lead to unpredictable behaviours.
    data["settings"]["rs_weights"] = {};
    data["settings"]["rs_weights"]["los_score"] = 0.4;
    data["settings"]["rs_weights"]["us_score"] = 0.4;
    data["settings"]["rs_weights"]["quality_score"] = 0.1;
    data["settings"]["rs_weights"]["popularity_score"] = 0.1;

4. Call the API

Finally, call the API with the data previously built.

    EuropeanaRS_API.callAPI(data,function(response){
      //On success
    }, function(error){
      //On error
    });

API Methods

The following methods, which can be called through the EuropeanaRS_API javascript object, are available in the EuropeanaRS API JavaScript library:

Method	Description	Params
callAPI	Call the main method of the EuropeanaRS API to request recommendations.	Parameters are described here.
createUser	Allows a web application to create a user profile using the EuropeanaRS Users API.	Parameters are described here.
updateUser	Allows a web application to update a user profile using the EuropeanaRS Users API.	Parameters are described here.
deleteUser	Allows a web application to delete a user profile using the EuropeanaRS Users API.	Parameters are described here.
getSettings	Get the settings of the EuropeanaRS API JavaScript instance.	-

Examples

In the following folder https://github.com/agordillo/EuropeanaRS/tree/master/extras/sampleApp_API of the EuropeanaRS repository there are some examples that shows different ways of using the EuropeanaRS API JavaScript library. Furthermore, there is a fully web application example showing how to use the EuropeanaRS API.