API Documentation

Modified: 2008/08/20 05:30 PM by headCodeWrangler - Categorized as: API, Documentation

Edit

Overview

The simple API is a REST based web service implementation for retrieving data from Ensemble Video. It is used internally by Quick Publish feature but it is also intended to be used by third party web sites and services to interact with the Ensemble Video application. The API can return data in two different formats: XML and JSON (Java Script Object Notation). The current version of the API supports several features:

  • Listing videos in a particular web site. This includes video metadata and related thumbnails so a video list can be created and showed on an external web site.
  • Showing individual video information. This includes all video metadata, previews/thumbnails, attachments, links, credits, etc.
  • Listing categories in a particular web site. 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, the conventions used to get the data are based on the REST conventions. This includes the REST verbs (list, show, add, edit) as well as a particular naming convention for the REST request. The first version of the API implements the "list" and "show" verbs:

  • list - used to list get a list of records such as list of video record
  • show - used to get an individual record such as individual video record

Edit

Possible Implementations

Since the API can return data in XML or JSON format, retrieving information can be done with any language that can parse XML or JSON. Some possible ways to take advantage the API are:

  • A web service based implementation that will consume the XML and output the data
  • A JavaScript implementation (with various JavaScript libraries such as Prototype.js or jQuery) that will consume the data in JSON format
  • A ASP.NET Ajax implementation

Edit

Naming Convention

Requests to the API have to follow a particular convention. Part of that includes the REST verbs defined above. The other parts have to do with the type of data being requested, the desired format of the data, the primary key needed to get to that data and any additional parameters. Therefore, a call to the API can be broken into several parts. Let's look at an example:

simpleAPI/category/list.xml/jTSRq3tf2kmiN0vjg-MjZw

simpleAPI - All API calls must start with "simpleAPI"

category - The name of the record you want to access. This has to be in singular form. The supported records are "video" and "category"

list - The REST verb indicating the action to be taken. While "list" will list all the records for a particular record type, "show" will only get information for a single record

xml - The format the data should be returned in. Supported formats are "xml" and "json"

jTSRq3tf2kmiN0vjg-MjZw - The primary key for the type of records you want to return (in this case the web site id).

The above call can also be made using query parameters:

simpleAPI/category/list.xml?webSiteID=jTSRq3tf2kmiN0vjg-MjZw

Note: “Short GUID” values are used when referencing primary keys such as video IDs or web site IDs.

Edit

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

Edit

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>

Edit

API Parameters

Individual parameters or a combination of parameters can be used when querying the API for data. These parameters are used only when listing more than one record (when using the "list" REST verb). Otherwise if returning individual video information, the primary key is used (see Naming Convention) so the ID parameters (such as videoID, categoryID and webSiteID) do not need to be exclusively specified:

simpleAPI/video/show.xml/ZCCpNouPKk6BAg6hYYALhA

is the same as

simpleAPI/video/show.xml?videoID=ZCCpNouPKk6BAg6hYYALhA

Edit

Parameter Definitions

  • videoID - The ID of the video record to return

  • webSiteID - The ID of the web site from which to get information

  • categoryID - The ID of the category record to return

  • categoryName - The name of the category record to return

  • orderBy - The field by which the information should be ordered. This could be any of the fields returned by the particular API call. If the field is invalid, this parameters will be ignored.

  • orderByDirection - The order direction to be used in combination with the orderBy parameter.

  • pageIndex - The current page of data to be returned. This parameter is used to implement paging in your video or category list.

  • pageSize - The number of records that should be returned per page. Used in combination with the pageIndex parameters.

  • resultsCount - The number of results to return.

  • searchString - The string to use when applying a search criteria to the particular API call.

Edit

Example Usage

  • Get a list of videos in a particular web site

simpleAPI/video/list.xml/jTSRq3tf2kmiN0vjg-MjZw

  • Get information for individual video

simpleAPI/video/show.xml/ZCCpNouPKk6BAg6hYYALhA

  • Get a list of 10 most recent videos

simpleAPI/video/list.xml/jTSRq3tf2kmiN0vjg-MjZw?orderBy=videoDate&orderByDirection=desc&resultsCount=10

  • Get a list of categories for a web site

simpleAPI/category/list.xml/jTSRq3tf2kmiN0vjg-MjZw

  • Get a list of videos in a web site that match a certain search criteria

simpleAPI/video/list.xml/jTSRq3tf2kmiN0vjg-MjZw?searchString=what

  • Get a list of videos in a web site ordered by video title in descending order

simpleAPI/video/list.xml/jTSRq3tf2kmiN0vjg-MjZw?orderBy=videoTitle&orderByDirection=desc

  • Get a list of videos in a web site with a certain category id

simpleAPI/video/list.xml/jTSRq3tf2kmiN0vjg-MjZw?categoryID=sy1IG95IzUyYLjwBcm_-yg

  • Get a list of videos in a web site with a certain category name

simpleAPI/video/list.xml/jTSRq3tf2kmiN0vjg-MjZw?categoryName=alumni%20and%20friends

  • Get a list of videos in a web site with a certain category name and limit the results to 1

simpleAPI/video/list.xml/jTSRq3tf2kmiN0vjg-MjZw?categoryName=alumni%20and%20friends&resultsCount=1

  • Get a list of videos in a web site with a certain category name but only the second page with page size of 1

simpleAPI/video/list.xml/jTSRq3tf2kmiN0vjg-MjZw?categoryName=alumni%20and%20friends&pageIndex=2&pageSize=20

Edit

More Examples

Retrieving a List of Videos in a Web Site

  • In XML format

simpleAPI/video/list.xml/jTSRq3tf2kmiN0vjg-MjZw

  • In JSON format

simpleAPI/video/list.json/jTSRq3tf2kmiN0vjg-MjZw

Retrieving Individual Video Information

  • In XML format

simpleAPI/video/show.xml/ZCCpNouPKk6BAg6hYYAlHa

  • In JSON format

simpleAPI/video/show.json/ZCCpNouPKk6BAg6hYYAlHa

Retrieving a Category List in a Web Site

  • In XML format

simpleAPI/category/list.xml/jTSRq3tf2kmiN0vjg-MjZw

  • In JSON format

simpleAPI/category/list.json/jTSRq3tf2kmiN0vjg-MjZw
Page Editing Help