JavaScript Example

We would like to make the usage of the API as easy as possible. Developers are (after the API registration) able to post events and to request context models. Everything that can be done with our API is described in detail in the API documentation. It is also described how requests can be sent. Since this can be at first to think of every detail in the implementation, we would like to offer a set of classes that can be easily integrated into a PHP project.

oauth-JS-4.1.zip

To use all the functionalities of this library in your webpages, just copy the files into your project directory and add these script tags to the head section of all your webpages that wants to interact with the API. Also add one crypto library which is used to generate sha512 hashes.

<script src="http://crypto-js.googlecode.com/svn/tags/3.1.2/build/rollups/sha512.js"></script>

<script src="scripts/LearningContext.js" type="text/javascript"></script>
<script src="scripts/LearningContextUtil.js" type="text/javascript"></script>
<script src="scripts/TokenManager.js" type="text/javascript"></script>
<script src="scripts/ContextData.js" type="text/javascript"></script>
<script src="scripts/Entity.js" type="text/javascript"></script>
<script src="scripts/Event.js" type="text/javascript"></script>

You can change the src attribute of these tags regarding to their relative address. As a result, the functionalities of this library are now available in your desired webpages. You won't have to worry about what has to be sent to the interface or how it should be formatted or calculated. The given library will take care of everything.

In this library, there is not a complex listener to react on the results of the server. It just pass the result string to your code. In other words, this is just a plain "sending something and waiting for the answer" method. To get started, you have to create an object of the type ContextData. It requires the URL and the version of the API, the username and password of one valid user, the app-ID and the app-secret (you should have received that after registering your app).

var lc = new LearningContext("http://api.learning-context.de",
	version, 
	appId, 
	appSecret,
	callbackURL,
	refreshToken;

In order to receive the refresh token after being redirected back to your website, the following code has to be added before defining the previously mentioned lc object.

(function(){
	var s = window.location.search.substring(1).split('&');
	if(!s.length) return;
	window.$_GET = {};
	for(var i  = 0; i < s.length; i++) {
		var parts = s[i].split('=');
		window.$_GET[unescape(parts[0])] = unescape(parts[1]);
	}
}())

This code receives the refresh token as GET parameter. If this website is called the first time, there are no GET parameters and the refresh token is an empty string. If the user is redirected back after approving the application, the GET parameter holds the valid refresh token. Therefore, the variable refreshToken of the lc object can be replaced with $_GET['rt'].

To send a GET request (e.g. receive a context model from the API) and show its related result, only two additional line of code is required:

var result = lc.get("events", '{"model":"COMPLETE"}');
console.log(result); 

The first parameter defines the name of the interface (in this case it is events). The second parameter is the request itself. It is a JSON string as described in the API documentation.

To send a POST request (e.g. send new events to the API), the event and its entities have to be created first. Here, we will create an event which indicates a new position at a given timestamp. As entities, any key-value pairs can be added to an event (see API Doc):

var event = new Event("START", "2015-10-15 12:12:12", "MOBILE", "PRIVATE", "POSITION");
var entity1 = new Entity("lng", "6.44");
var entity2 = new Entity("lat", "50.33");
event.addEntity(entity1);
event.addEntity(entity2);

To convert the event into its JSON representation, the class Event has its own function, called toJson(). Since the API requires you to send an Array of events, you can simply put [ ] around a comma separated set of events (each formatted as a JSON string). After that, the JSON string can be send analogous to the GET request:

var json = "[" + event.toJson() + "]";
console.log(lc.post("events", json);