The Javascript API library can be downloaded from: http://www.sesamevault.com/developer/js_sesamevault_api.zip.
This library allows developers to integrate the SesameVault API into their webpages with very little fuss, forgoing such messiness as building user authorization signatures and worrying about data exchange formats.
Once the SesameVault library has been included, you can create an API session by providing your username and password. For example:
Requests are made with the get function, where you provide the API call's URL path (without any file extension) and a callback function that acts on the results. Results are returned as a JSON object. For example, to get a video's metadata, you would call:
session.get('/video/info/[VIDEO ID]', function(results) {
// do something with the 'results' object ...
})
When you need to POST data to the server, you simply build a JSON object representing that data and send it as an optional third parameter to the get function. For example, to change a video's title, you would call:
var data = {
title: 'New Title Here'
}
session.get('/video/info/[VIDEO ID]', function(results) {
// do something with the 'results' object ...
}, data)
The result of POSTing data is the same: in the example above, a JSON object containing the video metadata (reflecting any changes that you've made).
(For details on how to properly form your arrays and on what the resulting returned arrays look like, check out the documentation on the individual API calls.)
You can retrieve a list of the videos in your vault using the standard API call vault/videos. But as this is such a common call, it has been encapsulated into the videos function which can take a number of parameters:
// all videos in your vault
session.videos('all', callback);
// just public videos
session.videos({public: true}, callback);
// videos that match the filter with id 7
session.videos({filter_id: 7}, callback);
// for each video, include information on the theora profile (e.g. size, urls, etc)
session.videos({include_profile: 'theora'}, callback);
// include information on the theora and iPod profiles
session.videos({include_profiles: ['theora', 'ipod5gen']}, callback);
// add a filter to the video search (videos tagged with "awesome" and "bunnies")
session.videos({filters: [[type: 'tag', data: 'awesome'],
[type: 'tag', data: 'bunnies']]}, callback);
These parameters can, of course, also be combined into a single query:
session.videos({public: true, filter_id: 7, include_profile: 'ipod5gen'}, callback);
To upload a file to SesameVault, POST it to http://www.sesamevault.com/upload/new/file
Before you do this, however, you will need to generate an upload key (which can also be used to track the progress of the upload), and an api signature to authorize the upload request.
To generate an upload key, use the new_upload_key function. The signature can be incorporated directly onto the url, using the add_sig_to_url function. You will need to pass to it the name of the file to be uploaded:
var filename = 'myfile.mp4';
session.new_upload_key(function(key) {
var upload_url = 'upload/new/file?upload_key=' + key;
upload_url = session.add_sig_to_url(upload_url, filename);
// use the upload_url inside your form
})
Note that filename should not include the path to the file, but only the name of the actual file itself.
You can use the upload key to request the progress of a currently ongoing upload, using the upload_progress function:
session.upload_progress(upload_key, function(progress) {
// progress['status']['received'] contains the number of bytes received by SesameVault so far
// progress['status']['size'] contains the total size of the file
})