This document contains information on the interfaces available to interact with the Ooyala Backlot system in a programmatic manner. All Backlot APIs are REST-based with a signature required for each request.
A list of conventions used in this document.
A flexible search interface for information on content stored in your Backlot account. In general, the information available in the grid of the Manage tab can be requested, along with basic performance data. For more intensive analytics queries, we recommend the Ooyala Analytics API documentation.
An interface that allows for retrieval of thumbnail images. Thumbnail images are automatically generated for content ingested to your Backlot account.
Update video attributes and delete unwanted content from your Backlot account.
Assign, query, and manage arbitrary key-value pairs associated with a video asset. This provides a powerful way to associate and use metadata with any content in your Backlot account.
Manage labels in your Ooyala Backlot account including associating content with labels.
List available players and assign embed codes to a particular player.
List and set your channel lineups.
List and set your channel set lineups.
Automate the creation of channels using labels, ordering information, embed codes, and/or a provider code.
Add high performance caching layer to API calls for repeated and non-unique requests.
Examples in PHP and Ruby.
Sign parameters to create a unique signature. Uses the Query API as an example.
We use the following conventions in this document:
API Specific KeywordsHighlighted words that have specific definitions within our APIs
<parameter>A parameter stand-in.
Code Snippets
Blocks of code. Sometimes this is also used to highlight important information. The box outline will not be included when the document is printed.
Information pertinent to the section.
To request information about content in a Backlot account, we offer a flexible query API. Requests are made through REST-style signed GET requests to http://api.ooyala.com/partner/query. Results are paginated with the page size set by the limit parameter and the requested page number set by the pageID parameter. When nextPageID has a value of -1, there are no further results to fetch.
Required search criteria parameters
Optional search criteria parameters
Video, VideoAd, Channel, MultiChannel, LiveStream, YouTube or RemoteAsset.embedCode. Multiple embedCode matches can be specified by using a comma-separated list.labelsmetadataratings – The ratings information is returned in a "movieRatings" XML element of the form: <movieRatings>4;3;2;0;0;0;0;0;0;0;0</movieRatings>. This element will be absent if the content item has no ratings yet.true or false. Specify whether or not to include content that has been deleted in the last 30 days in the query response.Defaults to false.<id>] – Match content having labels with fully-qualified names matching ALL given strings. Use alphanumeric characters for "id" portion of parameter.lifetime, 1d, 2d, 3d, 4d, 5d, 7d, 14d, 28d, 29d, 30d, 31dstatus matches can be specified using a comma-separated list.RemoteAsset – remote assetdeleted – video or channel removed from the systemlive - video or channel is error-free, processed, and can currently be playedscheduled - video or channel is error-free, processed, and is scheduled to be available sometime in the futurefinished airing - video or channel is error-free, processed, and no longer availableerror – pre or post processing errorfilemissing – upload stage erroruploading – file is currently being uploadedpaused – video cannot be played (user set state)uploaded – state between uploading and processingna – represents unknown contentcremoved – autosyndicated content which has been deleted and is no longer available in the destination account because it was deleted in the source accountauploading – 'a' here represents API, so this means it is an API upload. Every upload that does not occur through a Backlot interface is an API upload.auploaded – reference auploading, aboveduplicate – a duplicate file that we detected based off of name and file size within a particular accountpending – state that is practically the same as 'paused' but is named differently to denote that a moderation process of sorts is occurringprocessing – video is going through processinguploadedat or updatedat which correspond to when the asset was uploaded and last updated respectively. The order is specified by asc or desc. As an example, if one wanted to order the results in descending order by upload time: orderBy=uploadedAt,desc.Note: If multiple search parameters are specified, a valid match must satisfy all the parameters.
The result of a query is an XML document served as a response body. The root tag is <list>, and all matching content elements are included as <item> tags in that list. An example result follows in the next section.
Video, VideoAd, Channel, Alias, AliasAd, MultiChannel, Autosynddisplays, plays, rewinds, playtime, and watchedNote: Internal statuses exposed via the Query API may be slightly different from the statuses presented in the Backlot user interface.
<?xml version="1.0" encoding="UTF-8"?>
<list totalResults="277" nextPageID="10" size="2" statistics-as-of="1247507998"
statistics-as-of_text="Mon Jul 13 17:59:58 UTC 2009" limit="2" pageID="9">
<item>
<embedCode>RyY2IxOtfOye1qEPARlzC5S9oPt0tFeH</embedCode>
<title>MOV00821.MPG</title>
<description/>
<status>pending</status>
<content_type>Video</content_type>
<uploadedAt>1211529928</uploadedAt>
<length>12960</length>
<size>4708348</size>
<updatedAt>1211568871</updatedAt>
<flightStartTime>1211529928</flightStartTime>
<width>640</width>
<height>480</height>
<labels>
<label>/any/another</label>
<label>/any/some</label>
<label>/bysmthng/qqq</label>
<label>/byuser/u1</label>
</labels>
<metadata>
<metadataItem name="director" value="Francis Ford Coppola"/>
<metadataItem name="actor" value="Marlon Brando"/>
</metadata>
<thumbnail height="79" width="106">
http://ak.c.ooyala.com/RyY2IxOtfOye1qEPARlzC5S9oPt0tFeH/Ut_HKthATH4eww8X5iMDoxOmEzOxWwy3
</thumbnail>
<stat>
<lifetime>
<displays total="0"/>
<plays total="0"/>
<rewinds total="0"/>
<playtime ms="0"/>
<watched _25="0" _50="0" _75="0" _100="0"/>
</lifetime>
</stat>
</item>
</list>
For every video uploaded into your Backlot account, the Ooyala Transcoding system produces a thumbnail image roughly every 15-30 seconds. The encoding widths in your processing profile dictate the sizes of the images produced. Specifically, for every encoding width X in your processing profile, thumbnail images are produced at size X and size X/3. Any query to the Thumbnail API for a particular size of an image will as a result search against these sizes. If an exact match is not possible, the next closest sized thumbnail image will be returned. It is important to note that the thumbnail images produced maintain the aspect ratio of the original file uploaded into Backlot.
Note: Custom promo images uploaded through Backlot or the API will be returned by a thumbnail query and will not be processed and have multiple sizes made available. The thumbnail image is different from the promo image; the original promo image can be accessed through the Query API interface.
As in the Query API example, Thumbnail queries are generated using a signed REST-style GET request to http://api.ooyala.com/partner/thumbnails.
Required Parameters:
<from index>-<to-index>. For example, to get first 5 thumbnails (from index 0 to index 4) use this value: range=0-4. If the requested range is larger than the number of thumbnails generated, we will return all that are available.<width>x<height>, e.g. resolution=320x240. Please note that we may return a larger JPEG than requested, but with a higher compression rate. You may resize this result to the desired size.Example of a request
http://api.ooyala.com/partner/thumbnails?pcode=<pcode>&embedCode=<embedCode>
&range=0-25&resolution=600x400&expires=<expiration>&signature=<signature>The result of a query is an XML document served as a response body. The root tag is <thumbnails> with all matching thumbnails included as <thumbnail> tags in that list.
The root <thumbnails> tag has 2 attributes:
4/3 or 16/9. Please note that this attribute contains the aspect ratio of the image and always reflects the aspect ratio of the actual movie.Each <thumbnail> tag contains:
index attribute – Zero-based index of thumbnail.timestamp attribute – Time of the video, in milliseconds, at which the thumbnail was created.<?xml version="1.0" encoding="UTF-8"?>
<thumbnails aspectRatio="4/3" estimatedWidth="240" embedCode="kxYm06gFKXEleIHdyXNKeefx-QAu2yVp" requestedWidth="340">
<thumbnail timestamp="0" index="0">
http://ak.c.ooyala.com/kxYm06gFKXEleIHdyXNKeefx-QAu2yVp/Ut_HKthATH4eww8X5hMDoxOmc3O2T4mP
</thumbnail>
<thumbnail timestamp="9933" index="1">
http://ak.c.ooyala.com/kxYm06gFKXEleIHdyXNKeefx-QAu2yVp/67AQECG82s3QgdEn5hMToxOmc3OwZ8Ex
</thumbnail>
<promoThumbnail>
http://ak.c.ooyala.com/kxYm06gFKXEleIHdyXNKeefx-QAu2yVp/Ut_HKthATH4eww8X5hMDoxOmc3O2T4mP
</promoThumbnail>
</thumbnails>
The Attribute API includes the ability to update attributes of assets and channels. This allows for programmatic control over certain aspects including Title, Description, Status, Hosted At URL, etc. An update request returns a plain text document containing “OK” on success or error text if an issue is encountered. As in the Query API example, interaction with the Attribute API is through signed REST-style GET requests to http://api.ooyala.com/partner/edit.
Required Parameters:
Optional Parameters:
live, paused, or deleted. Paused leaves the video in your Backlot account, but makes it inaccessible to viewers. Deleted removes the video from your Backlot account and makes it inaccessible to viewers.http://api.ooyala.com/partner/edit?pcode=<pcode>&embedCode=<embedCode>&expires=<expiration>
&status=paused&title=updated%20title&signature=<signature>http://api.ooyala.com/partner/edit?pcode=<pcode>&embedCode=<embedCode>&expires=<expiration>
&hostedAt=http%3A%2F%2Fwww.ooyala.com%2Fbacklot&signature=<signature>The Custom Metadata API enables you to associate arbitrary name/value pairs with any of your assets. Metadata is manipulated using signed REST-style GET calls to http://api.ooyala.com/partner/set_metadata.
Required Parameters
Optional Parameters
Restrictions
Responses are XML with the following structure
<?xml version="1.0" encoding="UTF-8"?>
<result code="success">ok</result>When the request is successful, "code" will be "success". When the request is unsuccessful, "code" will be an HTTP status code indicating the reason for the failure.
As a reminder, all keys and values must be properly URI escaped.
Example:
http://api.ooyala.com/partner/set_metadata?pcode=<pcode>&signature=<signature>&expires=<expiration>&embedCode=<embedCode>&director=Francis%20Ford%20Coppola&actor=Marlon%20Brando&delete=writer%00copyright
This query will assign the value of "Francis Ford Coppola" to "director", the value "Marlon Brando" to "actor", and will delete the names "writer" and "copyright".
The Backlot Label API allows for programmatic control of labels. Included in the API are calls for label creation and deletion, association and removal of labels and content, and renaming of a label. As in the Query API example, interactions with the Backlot Label API are through signed REST-style GET requests to http://api.ooyala.com/partner/labels.
Responses are XML with the following structure
<?xml version="1.0" encoding="UTF-8"?>
<result code="success">ok</result>The code will be one of success, failure, params_missing. The xml response of the <result> tag will be 'ok' on success or an explanation of the error on failure.
Required Parameters
listLabels, createLabels, deleteLabels, assignLabels, unassignLabels, renameLabel, or clearLabelsReturns a list of labels in the given account.
Optional parameters: label - If this is provided, the sublabels of the specified label are returned. If this is not provided, all labels in the account are returned.
Example:
http://www.ooyala.com/partner/labels?pcode=<pcode>&expires=<expiration>
&mode=listLabels&signature=<signature>Additional required parameter: a comma-separated list of labels or a list of label[<id>]=label parameters
createLabels and deleteLabels allow for the creation and deletion of labels, respectively. Labels must start with a forward slash '/' and a tree structure can be specified in the usual manner: /grandparent/parent/child. Labels can be specified in one of two formats:
labels=<label1>,<label2>,<label3>label[1]=<label1>&label[2]=<label2>&label[3]=<label3>For label paths with multiple elements, such as /labelParent/labelChild, the entire path will be created including parent labels as needed.
Examples:
http://api.ooyala.com/partner/labels?pcode=<pcode>&expires=<expiration>&labels=/hello&
mode=createLabels&signature=<signature>
http://api.ooyala.com/partner/labels?pcode=<pcode>&expires=<expiration>&labels=/hello&mode=
deleteLabels&signature=<signature>Additional required parameters: embedCodes, labels (or label[
Optional parameters:
unassignLabels, remove any labels lower in the path. For example, if you have content associated with labels /parent and /parent/child, and remove /parent, /parent/child will be removed as well. Default is false.
unassignLabels, force a success return ('OK') if the specified label is not present. Default is false.
assignLabels, do not create the label if it does not exist. Default is true.
assignLabels and unassignLabels allow the assignment or removal of labels, respectively, with a set of videos. Labels can be specified in the same manner as above. Videos are specified as a comma-separated list of embed codes.
Examples:
http://api.ooyala.com/partner/labels?pcode=<pcode>&embedCodes=<embedCode1>,<embedCode2>
&expires=<expiration>&labels=/hello,/bye&mode=assignLabels&signature=<signature>
http://api.ooyala.com/partner/labels?pcode=<pcode>&embedCodes=<embedCode1>,<embedCode2>
&expires=<expiration>&labels=/hello,/bye&mode=unassignLabels&signature=<signature>Additional required parameters: oldlabel, newlabel
renameLabel allows you to rename or move a label without losing its associated videos. If newlabel has different ancestors from oldlabel, it will be moved appropriately. If the name is different, it will be renamed appropriately.
Example:
http://api.ooyala.com/partner/labels?pcode=<pcode>&embedCodes=<embedCode1>,<embedCode2>
&expires=<expiration>&mode=renameLabel&newlabel=/bye&oldlabel=/hello&signature=<signature>Additional required parameter: embedCodes
clearLabels allows the removal of all associated labels from a set of videos without enumerating the labels individually. Videos are specified as a comma-seperated list of embedCodes as with the assignLabels and unassignLabels modes.
Example:
http://api.ooyala.com/partner/labels?pcode=<pcode>&embedCodes=<embedCode1>&
expires=<expiration>&mode=clearLabels&signature=<signature>The Player Management API allows for the listing of available players and the assignment of a player to particular embed code(s). There are two modes, 'list' and 'assign'. As in the Query API, interaction with the Player Management API is through signed REST-style requests to http://api.ooyala.com/partner/players.
Required Parameters
list or assignList all avilable players. No additional parameters required.
Example:
http://www.ooyala.com/partner/players?pcode=<pcode>&expires=<expiration>&mode=list&signature=<signature>Result:
<?xml version="1.0" encoding="UTF-8"?>
<players size=1>
<player>
<pid>e870d9c7-cd69-4b56-b8fd-3cf10a83cf12</pid>
<name>Default Player</name>
</player>
</players>
Additional required parameters: embedCodes, pid
Assigns a comma-separated list of video embed codes (or a single embed code) to a particular player. An existing player will be overwritten when using this mode. Returns a text file with 'OK' on success or an error message on failure.
Example:
http://ooyala.com/partner/players?mode=assign&pcode=<pcode>&expires=<expiration>&embedCodes=9kaTUyOk20sGc8NM9ITgxkRWYlty68d4&pid=e870d9c7-cd69-4b56-b8fd-3cf10a83cf12&signature=<signature>The Channel API allows for the listing and setting of channel lineups. There are three modes, 'list', 'assign' and 'create'. As in the Query API, interaction with the Channel API is through signed REST-style requests to http://api.ooyala.com/partner/channels.
Required Parameters
list, assign, createList all channel components. No additional parameters required.
Example:
http://www.ooyala.com/partner/channels?pcode=<pcode>&channelEmbedCode=<channelEmbedCode>
&expires=<expiration>&mode=list&signature=<signature>Result:
<?xml version="1.0" encoding="UTF-8"?>
<channel>
<embedCode>9scDM426LtgO5kElm3ddWAExjw6uq7Rs</embedCode>
<title>New Channel</title>
<status>live</status>
<item>
<embedCode>w4adOyOiMjsW-58yCgrY92IOer3v_hAp</embedCode>
<title>demo.mp4</title>
<description></description>
<status>live</status>
<content_type>Video</content_type>
<uploadedAt>1217036203</uploadedAt>
<length>130766</length>
<size>23641511</size>
<updatedAt>1234765782</updatedAt>
</item>
</channel>
Additional required parameter: embedCodes
Assigns a comma-separated list of video embed codes (or a single embed code) to a channel embed code as a lineup. Embed codes for other channels or channel sets are invalid. An existing channel lineup will be overwritten when using this mode. Returns a text file with 'OK' on success or an error message on failure.
Example:
http://www.ooyala.com/partner/channels?pcode=<pcode>&channelEmbedCode=<channelEmbedCode>&embedCodes=<embedCode1>,<embedCode2>&expires=<expiration>&mode=assign&signature=<signature>Additional required parameter: title
Create a channel in Backlot with the given title.
Example:
http://www.ooyala.com/partner/channels?pcode=<pcode>&expires=<expiration>&mode=create&title=<channelTitle>&signature=<signature>Result:
<?xml version="1.0" encoding="UTF-8"?>
<channel>
<embedCode>R2NTZkMTpJ0i-YaH8cPuKwS_yHJgri7O</embedCode>
<title>My Channel Title</title>
<status>live</status>
</channel>
The Channel Set API allows for the listing and setting of channel set lineups. There are three modes, 'list', 'assign' and 'create'. As in the Query API, interaction with the Channel Set API is through signed REST-style requests to http://api.ooyala.com/partner/channels.
Required Parameters
list, assign, createAdditional required parameter: channelSetEmbedCode
List all channel set components.
Example:
http://www.ooyala.com/partner/channel_sets?pcode=<pcode>&channelSetEmbedCode=<channelSetEmbedCode>&expires=<expiration>&mode=list&signature=<signature>Result:
<?xml version="1.0" encoding="UTF-8"?>
<channelSet>
<embedCode>9scDM426LtgO5kElm3ddWAExjw6uq7Rs</embedCode>
<title>New Channel</title>
<status>live</status>
<channel>
<embedCode>w4adOyOiMjsW-58yCgrY92IOer3v_hAp</embedCode>
<title>demo channel</title>
<description></description>
<status>live</status>
<content_type>Channel</content_type>
<uploadedAt>1217036203</uploadedAt>
<length>130766</length>
<size>23641511</size>
<updatedAt>1234765782</updatedAt>
</channel>
</channelSet>
Additional required parameters: channelSetEmbedCode, channelEmbedCodes
Assigns a comma-separated list of channel embed codes (or a single channel embed code) to a channel set embed code as a lineup. Embed codes for other channels sets are invalid. An existing channel set lineup will be overwritten when using this mode. Returns a text file with 'OK' on success or an error message on failure.
Example:
http://www.ooyala.com/partner/channel_sets?pcode=<pcode>&channelSetEmbedCode=<channelSetEmbedCode>&channelEmbedCodes=<embedCode1>,<embedCode2>&expires=<expiration>&mode=assign&signature=<signature>Additional required parameter: title
Create a channel set in Backlot with the given title.
Example:
http://www.ooyala.com/partner/channel_sets?pcode=<pcode>&expires=<expiration>&mode=create&title=<channelSetTitle>&signature=<signature>Result:
<?xml version="1.0" encoding="UTF-8"?>
<channelSet>
<embedCode>R2NTZkMTpJ0i-YaH8cPuKwS_yHJgri7O</embedCode>
<title>My Channel Set Title</title>
<status>live</status>
</channelSet>
Dynamic channels are similar to standard Ooyala channels in that they display a series of videos, but different in that you are giving the player directions on what videos to play as opposed to an explicit list. These directions can include labels, ordering information, embed codes, and/or a provider code. All examples are given as query-string parameters to the embed code.
Basic channel creation requires either an embed code, provider code, or both. When the embedCode is specified, embedCode will take precedence and will be the first video displayed, followed by the other videos from the account given the sorting and ordering information. The simplest form of a dynamic channel is one beginning with a specified video and including all other video available from the account with the default ordering of most recent upload time.
embedCode=SAMPLE_VIDEO&labels=*
A full list of required and optional parameters are listed below along with more detailed examples.
Dynamic channels requests require a signature and expiration be added to the query string. Signing can be done in the same way as other API calls with the exception of the date. Instead of using an expiration of seconds since epoch, dynamic channels use an expiration format of YYYYMMDDhhmm.
For example, an expiration of 201012191844, represents 2010 December 19, 18:44.
For more details on signature generation please review the Signing section.
In order to specify that the embed is a dynamic channel the additional query string parameter dynamicChannel=true must be added to the embed.
Video selection can also be based off of labels:
labels=* – Includes all live videos in the account. (Excludes channels, channelsets, ads)labels=. – Includes all account content having the same label as the embedCode.labels='comma-separated list of URI-escaped labels' – Includes all account content matching the label list.There are several options to order the videos in a channel:
orderBy=uploadTime – Order lineup by most recently uploaded. (Default)orderBy=title – Order lineup alphabetically by title.orderBy=popularity – Order lineup by most played videos.orderBy=random – Order lineup randomly each time it is played.There are several options to order the videos in a channel:
orderDirection=asc – List videos in ascending order. (Default)orderDirection=desc – List videos in descending order.
limit – To specify a maximum number of videos to include in a channel. This defaults to 32 and has a maximum value of 100.Player parameters apply to Dynamic Channels as they do to standard channels:
transition – Specify play to show the next movie or specify selector to show the channel browser after each video in a channel. Default is play. view – Specify whether the initial state of the player is normal (shows the video) or the channel. Default is normal.browserPlacement – For a channel, specify where external controls are placed, either left or right. Can include a percentage or a width in pixels that will be occupied by the controls as in left40 for left and 40% of the width, or left200px to specify left and 200 pixels. The default left or right value is 50%.A full list of available player parameters can be reviewed in the Player API at http://www.ooyala.com/support/docs/player_api#parameters.
To protect the dynamic channel embed code from being misused, any videos included in a dynamic channel must be authorized for the domain the channel is embedded in (or ALL domains) or they will not be displayed.
Due to the highly dynamic nature of this type of channel, statistics are included on a per-video basis not on a per-channel basis.
These examples display the query string parameters and values necessary for a dynamic channel. Note that they do not include all parameters like height, width, signature, etc.
For example, to include all videos for the account with the pcode of 6Fna8C1JRtT8lupf86FFuoIgAD you would use:
pcode=6Fna8C1JRtT8lupf86FFuoIgAD&labels=*&dynamicChannel=true
20 most recently uploaded videos:
pcode=6Fna8C1JRtT8lupf86FFuoIgAD&labels=*&orderBy=UploadTime&orderDirection=desc&limit=20
10 most popular videos:
pcode=6Fna8C1JRtT8lupf86FFuoIgAD&labels=*&orderBy=popularity&orderDirection=desc&limit=10&dynamicChannel=true&expires=201104202311&signature=iznpYDyyfnm56oGEgFyQ%2FN6poHYnzlb%2BxDoqCoI7Fy3%2
Most recently uploaded video per a given label:
pcode=6Fna8C1JRtT8lupf86FFuoIgAD&labels=/music/pop&orderBy=uploadTime&orderDirection=desc&dynamicChannel=true&expires=201104200906&signature=34vfYD56fnmJMoGEgnzlb%2BxDoqFy3%2FyQ%2FN6poHYCoI7
First play a specific video and then all videos with a given label in random order:
embedCode=E390DSJKn802r2jnksn290&labels=/sports/football&orderBy=random&dynamicChannel=true&expires=201104202222&signature=anytYDyyfnmJMoGEg65poHYlb%2BxDoqCoI7Fy3%2FyQ%2FN6
In addition to our standard API, Ooyala also offers a high performance caching layer for API calls. This caching layer may not be necessary for all applications, but it is ideal for the following cases:
If both the above reflect your use case, we encourage you to consider using the high performance API and consult with your account manager on best practices.
Here is what you need to know when using the high performance API:
1) API calls need to be made to cdn.api.ooyala.com instead of api.ooyala.com.
2) While the high performance caching layer will keep a copy of your response for a few minutes, your expires parameter needs to be made "cache friendly." Unlike regular API calls where you'll often set the expires time to be just a few minutes from the current time, you'll find better performance setting it to a fixed time further out. For example, we can set it to always be the start of tomorrow with the following snippet:
today = Date.today
expires = Time.mktime(today.year, today.month, today.day) + 86400Alternatively, if you're generating urls to be used directly from a Flash / Flex application, you can simply pre-generate a url with an expires time years into the future.
3) High Performance doesn't mean it is better in all cases. Caching queries to the CDN is ideal for repeated, non-unique requests, but if you're generating unique requests (i.e. from search terms) each and every time, you'll want to query Ooyala directly.
Additionally, in scenarios where you always need the most up to date response, and can't wait a few minutes for a cached response to return, you should use api.ooyala.com
<?php
// You can find your Partner and Secret codes under the Developers
// area of the Backlot Account tab
define('OOYALA_PARTNER_CODE', '<Your Partner Code>');
define('OOYALA_SECRET_CODE', '<Your Secret Code>');
class OoyalaBacklotAPI
{
static function query($params)
{
return OoyalaBacklotAPI::send_request('query', $params);
}
static function query_thumbnails($params)
{
return OoyalaBacklotAPI::send_request('thumbnails', $params);
}
static function update($params)
{
return OoyalaBacklotAPI::send_request('edit', $params);
}
static function labels($params)
{
return OoyalaBacklotAPI::send_request('labels', $params);
}
static function metadata($params)
{
return OoyalaBacklotAPI::send_request('metadata', $params);
}
private static function send_request($request_type, $params)
{
// Add an expire time of 15 minutes unless otherwise specified
if (!array_key_exists('expires', $params)) {
$params['expires'] = time() + 900;
}
$string_to_sign = OOYALA_SECRET_CODE;
$url = 'http://api.ooyala.com/partner/'.$request_type.'?pcode='.OOYALA_PARTNER_CODE;
$keys = array_keys($params);
sort($keys);
foreach ($keys as $key) {
$string_to_sign .= $key.'='.$params[$key];
$url .= '&'.rawurlencode($key).'='.rawurlencode($params[$key]);
}
$digest = hash('sha256', $string_to_sign, true);
$signature = ereg_replace('=+$', '', trim(base64_encode($digest)));
$url .= '&signature='.rawurlencode($signature);
print "$url\n";
return file_get_contents($url);
}
}
// A few examples
$liveContent = OoyalaBacklotAPI::query(array('status' => 'live'));
$lifetimeStats = OoyalaBacklotAPI::query(array('statistics' => '1d,2d,7d,28d,30d,31d,lifetime', 'status' => 'live'));
$allTrailers = OoyalaBacklotAPI::query(array('label[0]' => 'trailers'));
$specificVideo = OoyalaBacklotAPI::query(array('embedCode' => 'plajrfuW5PS5rgc-kuc9ZWtFtdnYpfiK'));
$thumbnails = OoyalaBacklotAPI::query_thumbnails(array('embedCode' => 'plajrfuW5PS5rgc-kuc9ZWtFtdnYpfiK','range' =>
'0-99', 'resolution' => '320x240'));
$titleAndPause = OoyalaBacklotAPI::update(array('title' => 'updated title', 'status' => 'paused', 'embedCode' =>
'dhbjM6U-1s7YkieEwJRepTrYiPed8dPe'));
$hostedAt = OoyalaBacklotAPI::update(array('hostedAt' => 'http://www.ooyala.com/backlot', 'embedCode' =>
'dhbjM6U-1s7YkieEwJRepTrYiPed8dPe'));
$metaAssign = OoyalaBacklotAPI::metadata(array('metaMode' => 'add', 'embedCode' => 'dhbjM6U-1s7YkieEwJRepTrYiPed8dPe',
'type' => 'drama'));
$metaSearch = OoyalaBacklotAPI::metadata(array('metaMode' => 'query', 'embedCode' =>
'dhbjM6U-1s7YkieEwJRepTrYiPed8dPe'));
$labelClear = OoyalaBacklotAPI::labels(array('mode' => 'clearLabels', 'embedCodes' =>
'A5bjM6ugPkLWOxmmXxgk6fjJ22Kn60dw'));
?>
require "rubygems"
require "base64"
require "cgi"
require "digest/sha2"
require "open-uri"
module Ooyala
module Backlot
module API
# You can find your Partner and Secret codes under the Developers
# area of the Backlot Account tab
OOYALA_PARTNER_CODE = "<Your Partner Code>"
OOYALA_SECRET_CODE = "<Your Secret Code>"
def self.query(params)
return send_request("query", params)
end
def self.query_thumbnails(params)
return send_request("thumbnails", params)
end
def self.update(params)
return send_request("edit", params)
end
def self.labels(params)
return send_request("labels", params)
end
def self.metadata(params)
return send_request("metadata", params)
end
private
def self.send_request(request_type, params)
# Add an expire time of 15 minutes unless otherwise specified
params["expires"] ||= (Time.now.to_i + 10).to_s
string_to_sign = OOYALA_SECRET_CODE
url = "http://api.ooyala.com/partner/#{request_type}?pcode=#{OOYALA_PARTNER_CODE}"
params.keys.sort.each do |key|
string_to_sign += "#{key}=#{params[key]}"
url += "&#{CGI.escape(key)}=#{CGI.escape(params[key])}"
end
digest = Digest::SHA256.digest(string_to_sign)
signature = Base64::encode64(digest).chomp.gsub(/=+$/, '')
url += "&signature=#{CGI.escape(signature)}"
return open(url).readlines
end
end
end
end
# A few examples:
liveContent = Ooyala::Backlot::API::query("status" => "live")
lifetimeStats = Ooyala::Backlot::API::query(
"statistics" => "1d,2d,7d,28d,30d,31d,lifetime",
"status" => "live")
allTrailers = Ooyala::Backlot::API::query("label[0]" => "trailers")
specificVideo = Ooyala::Backlot::API::query("embedCode" => "plajrfuW5PS5rgc-kuc9ZWtFtdnYpfiK")
thumbnails = Ooyala::Backlot::API::query_thumbnails(
"embedCode" => "plajrfuW5PS5rgc-kuc9ZWtFtdnYpfiK",
"range" => "0-99",
"resolution" => "320x240")
titleAndPause = Ooyala::Backlot::API::update(
"title" => "updated title",
"status" => "paused",
"embedCode" => "dhbjM6U-1s7YkieEwJRepTrYiPed8dPe");
hostedAt = Ooyala::Backlot::API::update(
"hostedAt" => "http://www.ooyala.com/backlot",
"embedCode" => "dhbjM6U-1s7YkieEwJRepTrYiPed8dPe");
metaAssign = Ooyala::Backlot::API::metadata(
"metaMode" => "add",
"embedCode" => "dhbjM6U-1s7YkieEwJRepTrYiPed8dPe",
"type" => "drama");
metaSearch = Ooyala::Backlot::API::metadata(
"metaMode" => "query",
"embedCode" => "dhbjM6U-1s7YkieEwJRepTrYiPed8dPe");
labelClear = Ooyala::Backlot::API::labels(
"mode" => "clearLabels",
"embedCodes" => "A5bjM6ugPkLWOxmmXxgk6fjJ22Kn60dw");
API queries are required to be signed in order to ensure account security. We present these steps as an example of generating a signed API request. The query produced in this example is valid and illustrates how to compose and sign a qualified request. A detailed signing example is available here
Account-specific codes for Provider ID (pcode) and Secret (secret) can be found in Backlot Account tab under Developers. The pcode is 28 characters long, and the Secret Code is 40 characters long. Both are case sensitive and include alphanumeric characters, dashes (-), and underscores (_). These codes are required to generate a signature for each request to and from the Ooyala servers.
Partner Code:Note: These parameters point to a shared account accessible via API to any Backlot partner for preliminary testing. Content and metadata uploaded to this account is visible to all users.lsNTrbQBqCQbH-VA6ALCshAHLWrVSecret Code:hn-Rw2ZH-YwllUYkklL5Zo_7lWJVkrbShZPb5CD1
The pcode, secret code, all required parameters, and all included optional parameters are used to generate a SHA-256 signature for the call. We present this example on how to generate a signature and URI-encode the parameters for the call.
hn-Rw2ZH-YwllUYkklL5Zo_7lWJVkrbShZPb5CD1<name>=<value> pairs to the string. The SHA-256 signature is generated with the result, which does not include the pcode.This example uses expires=1893013926, label[0]=any/some, statistics=1d,2d,7d,28d,30d,31d,lifetime, status=upl,live, and title=a.
hn-Rw2ZH-YwllUYkklL5Zo_7lWJVkrbShZPb5CD1expires=1893013926label[0]=any/somestatistics=1d,2d,7d,28d,30d,31d, lifetime,status=upl,live,title=adDiJo3LKLqPnqCpzEHDYBBNBe%2FmBgV3%2BVt9eiTgFYGkhttp://www.ooyala.com/api/partner? and the Partner Code from the Developers area of your Backlot Account tab. Append the query parameters in alphabetic order, separated with & and end with signature=<signature> to include the digest computed in Step 3.
Note: All parameters must be URI-escaped before being added to the query. Parameters should be URI-escaped in the query, not when generating the signature.
http://www.ooyala.com/partner/query?pcode=lsNTrbQBqCQbH-VA6ALCshAHLWrV&expires=1893013926&label[0]=any/some&statistics=1d,2d,7d,28d,30d,31d,lifetime,&status=upl,live,&title=a&signature=dDiJo3LKLqPnqCpzEHDYBBNBe%2FmBgV3%2BVt9eiTgFYGk