The Ruby API library can be downloaded from: http://www.sesamevault.com/developer/ruby_sesamevault_api.zip.
This library allows developers to integrate the SesameVault API into their Ruby applications with very little fuss, forgoing such messiness as building user authorization signatures and worrying about data exchange formats.
Once the SesameVault module has been included (e.g., require "sesamevault_api.rb"), you can create an API session by providing your username and password. For example:
Requests are made with the get method, where you provide the API call's URL path (without any file extension) and a block that acts on the results. Results are returned as either an array or Ruby hash. For example, to get a video's metadata, you would call::
session.get('/video/info/[VIDEO ID]') do |results|
# do something with the 'results' hash ...
end
When you need to POST data to the server, you simply build a Ruby hash representing that data and call the send_to_sesame method on that hash, again providing the URL path and callback block. For example, to change a video's title, you would call:
data = {
'title' => 'New Title Here'
}
data.send_to_sesame(session, '/video/info/[VIDEO ID]') do |results|
# do something with the 'results' hash ...
end
The result of POSTing data is the same: in the example above, a hash 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 method which can take a number of parameters:
# all videos in your vault
session.videos
# just public videos
session.videos(:public => true)
# videos that match the filter with id 7
session.videos(:filter_id => 7)
# for each video, include information on the theora profile (e.g. size, urls, etc)
session.videos(:include_profile => :theora)
# include information on the theora and iPod profiles
session.videos(:include_profiles => [:theora, :ipod5gen])
# add a filter to the video search (videos tagged with "awesome" and "bunnies")
session.videos(:filters => [[:type => 'tag', :data => 'awesome'],
[:type => 'tag', :data => 'bunnies']])
These parameters can, of course, also be combined into a single query:
session.videos(:public => true, :filter_id => 7, :include_profile => :ipod5gen)
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 method. The signature can be incorporated directly onto the url, using the add_sig_to_url method. You will need to pass to it the name of the file to be uploaded:
upload_key = session.new_upload_key upload_url = 'upload/new/file?upload_key=' + upload_key filename = 'myfile.mp4' upload_url = session.add_sig_to_url(upload_url, filename)
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 method:
session.upload_progress(upload_key) do |progress|
# progress[:status][:received] contains the number of bytes received by SesameVault so far
# progress[:status][:size] contains the total size of the file
end