The PHP API library can be downloaded from: http://www.sesamevault.com/developer/php_sesamevault_api.zip.
This library allows developers to integrate the SesameVault API into their PHP applications with very little fuss, forgoing such messiness as building user authorization signatures and worrying about data exchange formats.
Note: This library requires the PECL JSON library to be installed with PHP. If you're using PHP 5.2.0 or later, it comes installed by default. If you are using an earlier version, you can download the JSON library from http://pecl.php.net/package/json.
Once the PHP file has been included (e.g., require_once("sesamevault_api.php")), 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). Results are returned as a PHP array. For example, to get a video's metadata, you would call:
$results = $session->get('/video/info/[VIDEO ID]');
// do something with the '$results' array ...
When you need to POST data to the server, you simply build an associative array representing that data and pass it as the second parameter to the get() method. For example, to change a video's title, you would call:
$data = array(
'title' => 'New Title Here'
);
$results = $session->get('/video/info/[VIDEO ID]', $data);
// do something with the '$results' array ...
The result of POSTing data is the same: in the examples above, an array 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 sent in as an array:
# all videos in your vault
$session->videos();
# just public videos
$session->videos(array('public' => true));
# videos that match the filter with id 7
$session->videos(array('filter_id' => 7));
# for each video, include information on the theora profile (e.g. size, urls, etc)
$session->videos(array('include_profile' => 'theora'));
# include information on the theora and iPod profiles
$session->videos(array('include_profiles' => array('theora', 'ipod5gen')));
# add a filter to the video search (videos tagged with "awesome" and "bunnies")
$filters = array(array('type' => 'tag', 'data' => 'awesome'),
array('type' => 'tag', 'data' => 'bunnies'));
$session->videos(array('filters' => $filters));
These parameters can, of course, also be combined into a single query:
$session->videos(array('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:
$results = $session->upload_progress($upload_key); // $results['status']['received'] contains the number of bytes received by SesameVault so far // $results['status']['size'] contains the total size of the file