Contents
- 1 Overview
- 2 API Parameters
- 3 Examples
- 4 Types of Data
- 5 Example Data
- 6 Tips and Tricks
- 7 Conclusion
Overview
The simple publishing API is a REST-based web service for retrieving data from the Ensemble Video application. It is inteded to be used by third party web sites and services to interact with the Ensemble Video application. The API can return data in three different formats: XML and JSON (Java Script Object Notation), JSONP (implementation of JSON that allows cross-domain data transfer - v3.2.1 and above). You can use any programming language that supports XML/HTTP transfer and can parse either XML or JSON. The first version of the API supports several features:
- Listing videos in a particular web destination: This includes video metadata and thumnails so that video lists can be created and published on an external web sites.
- Showing invidividual video information: This includes all video metadata, video encodings, previews/thumnails, attachments, links, credits, etc.
- Listing categories in a particular web destination: This includes information related to each category in a particular web site.
- Extensive parameters to query and filter the data to be returned
Since the API implements the REST protocol, our API calls follow typical REST conventions. This includes the REST verbs (list, show,add,edit). The most recent version of the API supports the "list" and "show" verbs only:
- List - used to list get a list of records such as listing of videos in a web destination
- Show - used to get an individual record such an single video
A REST procedure call is a very structured HTTP call that will return the type of object specified in the call. Below are the parts of an API call and an example that returns the XML for all videos in a web desination:
Example API Call
- API Root - http://cloud.ensemblevideo.com/ensemble/app/simpleapi
Base URL that must be included to start the API call - Data Object - /video
The type of data you want to return (video or category) - REST Verb - /list
How you want the data to be returned (list or show) - Return Format - .xml
What type of data you want to return (XML or JSON(P)) - Data ID - /4M2akAsn2EGhYH9edW8YSA
ID of the web destination or video - API Parameters - ?resultsCount=10
Parameters for the query. A full list can be found below .
API Parameters
Parameter Name | Description | Values (Default) |
---|---|---|
categoryID* | categoryID obtained from Ensemble Video application | Guid or ShortGuid (none) |
categoryName | text value of the category (this category must exist in the web destination you are querying against) | String (none) |
orderBy | specifies the field name/attribute to order the query by | String (ID field) |
orderByDirection | specifies sorting order; used in combination with the orderBy parameter | String 'asc' or 'desc' ('asc') |
pageIndex | indicates current page in the results set you want to display | Integer (0) |
pageSize | indicates how many content items to return per page | Integer (20) |
resultsCount | max amount of records you want returned with your query | Integer (all records) |
searchString | use this parameter for perform searches from your app | String (none) |
videoID* | videoID obtained from Ensemble Video Application | Guid or ShortGuid (none) |
websiteID* | websiteID obtained from Ensemble Video Application | Guid or ShortGuid (none) |
* ID fields can be called explicitly in API parameters or can be used as part of the base URI. The following calls produce the same result:
http://cloud.ensemblevideo.com/ensemble/app/simpleapi/video/list.xml/4M2akAsn2EGhYH9edW8YSA
http://cloud.ensemblevideo.com/ensemble/app/simpleapi/video/list.xml/?websiteID=4M2akAsn2EGhYH9edW8YSA
Examples
- Get a list of videos in a particular web site
http://cloud.ensemblevideo.com/ensemble/app/simpleapi/video/list.xml/4M2akAsn2EGhYH9edW8YSA
- Get information for individual video
http://cloud.ensemblevideo.com/ensemble/app/simpleapi/video/show.xml/ic2w-dvGpEu5T5dB4DBeFQ
- Get a list of 10 most recent videos
- Get a list of categories for a web site
http://cloud.ensemblevideo.com/ensemble/app/simpleapi/category/list.xml/4M2akAsn2EGhYH9edW8YSA
Types of Data
The current version of the API can return 3 distinct types of data:
- A list of videos published in Ensemble Video
- A list of categories used in Ensemble Video
- Detailed video information
Each set of data can be filtered and sorted by using the API parameters specified below. However, since each type of data contains different information, here is a list of columns returned by each type:
- The video list (without category constraint)
-
-
Field Name videoID videoDate videoDescription videoTitle videoDuration videoKeywords thumbnailUrl webSiteID webSiteName departmentID departmentName departmentWebSite departmentLogo
-
- The video list (with category constraint)
-
-
Field Name videoID videoDate videoDescription videoTitle videoDuration videoKeywords thumbnailUrl webSiteID webSiteName categoryID categoryName departmentID departmentName departmentWebSite departmentLogo
-
- The category list
-
-
Field Name categoryID categoryName webSiteID websiteName departmentID departmentName departmentWebSite departmentLogo
-
- Detailed video information
-
- Data returned for the individual content is contained in a complex type (XML) or a structure (JSON). Please see the XML example of data returned for the individual video.
-
-
Complex Type departmentInformation videoInformation videoImages videoEncodings videoAttachments videoLinks videoGenres videoRatings videoStatistics contentTypePlayers
-
Example Data
- Video list in XML format
<videos> <video> <videoID>e1P4G0MuCUeL0LTBz1xabQ</videoID> <videoDate>2008-07-10T13:20:13-04:00</videoDate> <videoDescription>One Small step for man video</videoDescription> <videoTitle>One Small Step for Man</videoTitle> <videoDuration>00:01:00</videoDuration> <videoKeywords/> <thumbnailUrl>http://demo.ensemblevideo.com/ensemble/app/files/1bf8537b-2e43-4709-8bd0-b4c1cf5c5a6d/thumb/OneSmallStepForMan_thumb05.jpg</thumbnailUrl> <webSiteID>OJkxH-bafkaKYRmJo11EQA</webSiteID> <webSiteName>Demo</webSiteName> <departmentID>tpgodoXPnUKvWOA8eg7HYQ</departmentID> <departmentName>Demo Department</departmentName> <departmentWebSite>http://demo.ensemblevideo.com</departmentWebSite> <departmentLogo/> </video> <video> <videoID>pWy7JqK0WUWvq61MQXTFIw</videoID> <videoDate>2008-05-28T16:13:39-04:00</videoDate> <videoDescription>Test video upload</videoDescription> <videoTitle>Test Video - Grizzly Bear!!</videoTitle> <videoDuration>00:01:00</videoDuration> <videoKeywords/> <thumbnailUrl>http://demo.ensemblevideo.com/ensemble/app/files/26bb6ca5-b4a2-4559-afab-ad4c4174c523/thumb/Bear - Copy - Copy_thumb02.jpg</thumbnailUrl> <webSiteID>OJkxH-bafkaKYRmJo11EQA</webSiteID> <webSiteName>Demo</webSiteName> <departmentID>tpgodoXPnUKvWOA8eg7HYQ</departmentID> <departmentName>Demo Department</departmentName> <departmentWebSite>http://demo.ensemblevideo.com</departmentWebSite> <departmentLogo/> </video> </videos>
- Video list in JSON format
var _xsajax$transport_status = 200; var data = { videos: { video: [ { "departmentID": "tpgodoXPnUKvWOA8eg7HYQ", "departmentLogo": null, "departmentName": "Demo Department", "departmentWebSite": "http://demo.ensemblevideo.com", "thumbnailUrl": "http://demo.ensemblevideo.com/ensemble/app/files/1bf8537b-2e43-4709-8bd0-b4c1cf5c5a6d/thumb/OneSmallStepForMan_thumb05.jpg", "videoDate": "2008-07-10T13:20:13-04:00", "videoDescription": "One Small step for man video", "videoDuration": "00:01:00", "videoID": "e1P4G0MuCUeL0LTBz1xabQ", "videoKeywords": null, "videoTitle": "One Small Step for Man", "webSiteID": "OJkxH-bafkaKYRmJo11EQA", "webSiteName": "Demo" } , { "departmentID": "tpgodoXPnUKvWOA8eg7HYQ", "departmentLogo": null, "departmentName": "Demo Department", "departmentWebSite": "http://demo.ensemblevideo.com", "thumbnailUrl": "http://demo.ensemblevideo.com/ensemble/app/files/26bb6ca5-b4a2-4559-afab-ad4c4174c523/thumb/Bear - Copy - Copy_thumb02.jpg", "videoDate": "2008-05-28T16:13:39-04:00", "videoDescription": "Test video upload", "videoDuration": "00:01:00", "videoID": "pWy7JqK0WUWvq61MQXTFIw", "videoKeywords": null, "videoTitle": "Test Video - Grizzly Bear!!", "webSiteID": "OJkxH-bafkaKYRmJo11EQA", "webSiteName": "Demo" } ]}};
- Video Details in XML format
<videos> <departmentInformation> <departmentID>tpgodoXPnUKvWOA8eg7HYQ</departmentID> <departmentName>Demo Department</departmentName> <departmentLogo/> <departmentWebSite>http://demo.ensemblevideo.com</departmentWebSite> </departmentInformation> <videoInformation> <videoID>52G4RwAa-0SYZDrlGNFD1g</videoID> <primaryTitle>UB Paints</primaryTitle> <abstract>UB in the community</abstract> <genre>6bb95d8c-572b-46c2-8448-2fba237f65b4</genre> <keywords>UB Paints</keywords> <duration>00:02:00</duration> <dateProduced>2008-06-23T00:00:00-04:00</dateProduced> <dateAdded>2008-06-23T10:13:39-04:00</dateAdded> <dateUpdated>2008-06-23T11:20:41-04:00</dateUpdated> <copyright/> <isPublished>true</isPublished> </videoInformation> <videoImages> <imageUrl>http://demo.ensemblevideo.com/ensemble/app/files/47b861e7-1a00-44fb-9864-3ae518d143d6/selectedImages/UB_PAINTS_FINAL_for_web_thumb05.jpg</imageUrl> <imageType>Preview</imageType> </videoImages> <videoImages> <imageUrl>http://demo.ensemblevideo.com/ensemble/app/files/47b861e7-1a00-44fb-9864-3ae518d143d6/thumb/UB_PAINTS_FINAL_for_web_thumb05.jpg</imageUrl> <imageType>thumb</imageType> </videoImages> <videoEncodings> <videoID>47b861e7-1a00-44fb-9864-3ae518d143d6</videoID> <departmentID>762898b6-cf85-429d-af58-e03c7a0ec761</departmentID> <videoSourceID>48e843ee-e756-4bbe-ac16-84aff76a285f</videoSourceID> <videoSourceTypeID>1</videoSourceTypeID> <encodingID>115da45f-b63c-44b9-a01f-2914537993d5</encodingID> <relativePath>C:\Inetpub\wwwroot\videos</relativePath> <absolutePath>http://demo.ensemblevideo.com/videos</absolutePath> <fullFilePath>http://demo.ensemblevideo.com/videos/UB_PAINTS_FINAL_for_web.mov</fullFilePath> <bitRate>0</bitRate> <departmentBandwidthLabelID>9e7a1f45-d1be-4503-80c5-0a6aab8b3a14</departmentBandwidthLabelID> <bandwidthDescription>High Bandwidth</bandwidthDescription> <dimensions>Select</dimensions> <fileName>UB_PAINTS_FINAL_for_web.mov</fileName> <videoSize>11 MB</videoSize> <uploadManual>Upload</uploadManual> <md5Hash>f2cb0d6deadf7c5e418d5a2582220420</md5Hash> <videoFormat>video/quicktime</videoFormat> <videoFormatIconImage>http://demo.ensemblevideo.com/ensemble/app/images/video-quicktime.gif</videoFormatIconImage> <useEmbeddedPlayer>false</useEmbeddedPlayer> </videoEncodings> <videoAttachments> <name>UB Paints</name> <url>http://demo.ensemblevideo.com/ensemble/app/files/47b861e7-1a00-44fb-9864-3ae518d143d6/attachments/UB_PAINTS_FINAL_for_web.mov</url> <format>mov</format> <type>video/quicktime</type> <typeIconImageUrl>http://demo.ensemblevideo.com/ensemble/app/images/video-quicktime.gif</typeIconImageUrl> <size>11 MB</size> <description/> </videoAttachments> <videoAttachments> <name>UB Paints</name> <url>http://demo.ensemblevideo.com/ensemble/app/files/47b861e7-1a00-44fb-9864-3ae518d143d6/attachments/UB_PAINTS_FINAL_for_web.mov</url> <format>mov</format> <type>video/quicktime</type> <typeIconImageUrl>http://demo.ensemblevideo.com/ensemble/app/images/video-quicktime.gif</typeIconImageUrl> <size>11 MB</size> <description/> </videoAttachments> <videoLinks/> <videoCredits/> <videoGenres> <genreName>Documentary</genreName> </videoGenres> <videoRatings/> <videoStatistics> <totalViews>8</totalViews> <totalUsers>3</totalUsers> <averageDailyViews>4</averageDailyViews> <averageRating>0</averageRating> <numberOfRatings>0</numberOfRatings> </videoStatistics> <contentTypePlayers> <imageUrl>http://demo.ensemblevideo.com/ensemble/app/images/contentTypePlayers/getQuickTimePlayer.gif</imageUrl> <downloadUrl>http://www.apple.com/quicktime/download</downloadUrl> </contentTypePlayers> </videos>
Tips and Tricks
Integrating the Ensemble Video Player
When building your own video site, it can be very cumbersome to build out your own player. Below is an example of how you could use the Ensemble Video player by using a mash-up of the HTML/JS video embed code, and the Ensemble Video API.
You can use an API call to get the contentID (also known as videoID). From there you can write a script to build out the embed code. You would just take the appropriate contentID and insert it in the proper place for the script tag. Below is a template example of how you might insert our player into your page. Simply replace the placeholder values with your Ensemble Server and ContentID. That video should now play on your site, using our player.
<div id="ensembleEmbeddedContent_{YOUR CONTENT ID}" class="ensembleEmbeddedContent" style="width: 640px; height: 390px;">
<script type="text/javascript" src="{YOUR ENSEMBLE SERVER}/app/plugin/plugin.aspx?
contentID={YOUR CONTENT ID}&useIFrame=true&embed=true&displayTitle=false&startTime=0&autoPlay=false&
hideControls=false&showCaptions=false&width=640&height=360"></script>
</div>
The advantages to using this are that we do automatic client checking and present an HTML 5 compatible player when necessary and possible.
Conclusion
There is a lot you can do with our API and publishing tools. If you need further assistance with the API or have any other questions about our system, please contact us at techsupport@ensemblevideo.com