JavaScript driver for little.io
JavaScript
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
tests
license.txt
little.jquery.js
readme.md

readme.md

little.io JavaScript Library

This is a jquery-powered javascript library for the http://little.io services.

Security and Method Signing

Many of little.io api calls require the request to include an SHA1 signature. This signature is comprised of various query parameters as well as your application's secret key. Generating this signature on the client would expose your secret and allow anyone to generate fake requests on your behalf.

As a workaround, the signature should be generated on the backend. To make this possible only the parameters which you'll know ahead of time are used for signing. For example the signature to tag an asset is based on the user, asset and type parameters (not the shared or data parameters which will likely be entered client-side). Conversely, to create a login attempt, which is of a much higher security concern, all parameters are part of the signature. This approach attempts to balance security with ease of use.

All this to say that when using the JavaScript library, you'll still need to generate your signatures server-side. The server-side drivers provide signature helpers.

Usage

With the js file included in your page, you can create a little object via:

var little = new LittleIO('YOUR_API_KEY');

This instance can now be used to call various methods:

little.asset.userAsset('leto', 'spice', 1, function(r) {... });

An example of calling a method which requires a signature, while using the ruby drivers:

little.user.attempts('<%= Little::Attempt.sign_get(@current_user.email) %>', '<%= Little::Attempt.sign_get(@current_user.email) %>', function(attempts){...});

The last parameter is always the callback to execute once a response is received. The callback is always optional

Asset and Type

An asset is always identified by the combination of an asset value and a type. This allows asset names to be reused for different objects (type 1 might be movies, and type 2 might be books and each of those might have an asset identified by '193').

Assets API

//votes for an asset
little.asset.vote(user, asset, type, 1 or -1, signature)

//rates an asset
little.asset.rate(user, asset, type, rating, signature)

//retrives a specific user/asset/type record
little.asset.userAsset(user, asset, type, callback)

//the user's assets
little.asset.forUser(user, page, records, callback)

//the user's asset count
little.asset.forUserCount(user, callback)

//the user's assets filtered for vote and rating (these should be null, true or false)
little.asset.filteredForUser(user, vote, rating, page, records, callback)

//the user's assets count filtered for vote and rating (these should be null, true or false)
little.asset.filteredForUserCount(user, callback)

//a paged list of assets by asset
little.asset.forAsset(asset, type, page, records, callback)

//the number of records for the asset
little.asset.forAssetCount(asset, type, callback)

//a paged list of assets by asset filtered for vote and rating (these should be null, true or false)
little.asset.filteredForAsset(asset, type, vote, rating, page, records, callback)

//the number of records for the asset filtered for vote and rating (these should be null, true or false)
little.asset.filteredForAssetCount(asset, type, vote, rating callback)

//the assets by type ordered by rating desc
little.asset.highestRated(type, page, records, callback)

//the assets by type ordered by votes desc 
little.asset.mostVotes(type, page, records, callback)

//the number of assets for the specified type
little.asset.countByType(type, callback)

Tags API

When creating a tag you specify whether it is shared (public) or not. When retrieving tags for a user you can specify whether you want only shared tags or all tags. If you want all tags you include the signature. If you only want public tags, you don't include the signature.

//returns the id of the tag
little.tag.add(user, asset, type, share, signature, [data], callback) 

//the tag by id. Omitting the signature will only get the tag if it's shared
little.tag.getById(id, [signature], callback)

//the tags for the user
forUser(user, page, records, [signature], callback)

//the number of tags the user has
forUserCount(user, [signature], callback)

//the tags for the user for the specified asset
forUserAndAsset(user, asset, type, page, records, [signature], callback)

//the number of tags the user has for the specified asset
forUserAndAssetCount(user, asset, type, [signature], callback)

//all shared tags for the asset (from all users) (cannot get private tags this way)
forAsset(asset, type, page, records, callback)

//the number of tags for the asset
forAssetCount(asset, type, callback)

Notifications API

Once a user has responded to a notification, that notification will no longer be retrieved for the user.

//gets the notification for a user for a specific type
little.notification.get(user, type, callback)

//responds to the notification (response should be an integer)
little.notitificaiton.respond(user, notification_id, response, signature, callback)

Users API

//the login attempts for the user. Omitting count returns the previous successful attempt
little.user.attempts(user, signature, [count], callback)