Difference between revisions of "Main Page"

From Wiki
Jump to: navigation, search
Line 1: Line 1:
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:
+
===Overview===
  
    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.
+
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: [http://www.w3.org/XML/|XML] and [http://json.org/|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:
    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
+
  
 +
*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:
+
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
+
*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
+
*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:
  
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=====
 +
http://cloud.ensemblevideo.com/ensemble/app/simpleapi/video/list.xml/4M2akAsn2EGhYH9edW8YSA?resultsCount=10
 +
 
 +
#'''API Root - http://cloud.ensemblevideo.com/ensemble/app/simpleapi''' <br />Base URL that must be included to start the API call
 +
#'''Data Object - /video''' <br />The type of data you want to return (video or category)
 +
#'''REST Verb - /list''' <br />How you want the data to be returned (list or show)
 +
#'''Return Format - .xml''' <br />What type of data you want to return (XML or JSON(P))
 +
#'''Data ID - /4M2akAsn2EGhYH9edW8YSA''' <br />ID of the web destination or video
 +
#'''API Parameters - ?resultsCount=10''' <br />Parameters for the query. A full list can be found below under [#params|API Parameters].
 +
 
 +
[anchor|#params]
 +
 
 +
===API Parameters===
 +
 
 +
{| cellpadding="5"
 +
|- style="background-color: Grey; color: White;"
 +
! 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)
 +
|}
 +
 
 +
&#42; 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 <br />[http://cloud.ensemblevideo.com/ensemble/app/simpleapi/video/list.xml/4M2akAsn2EGhYH9edW8YSA|]
 +
* Get information for individual video <br />[http://cloud.ensemblevideo.com/ensemble/app/simpleapi/video/show.xml/ic2w-dvGpEu5T5dB4DBeFQ|]
 +
* Get a list of 10 most recent videos <br />[http://cloud.ensemblevideo.com/ensemble/app/simpleapi/video/list.xml/4M2akAsn2EGhYH9edW8YSA?orderBy=videoTitle&orderByDirection=desc&resultsCount=10|]
 +
* Get a list of categories for a web site <br />[http://cloud.ensemblevideo.com/ensemble/app/simpleapi/category/list.xml/4M2akAsn2EGhYH9edW8YSA|]
 +
 
 +
===API Projects===
 +
 
 +
[http://video.syr.edu|Syracuse University Video Showcase]
 +
[http://whitman.syr.edu/video|Whitman School Video Showcase (Syracuse University)]
 +
[http://dev.ensemblevideo.com/starterkit|Ensemble Video Portal Starter Kit]
 +
[http://whitman.syr.edu/EBV/Video/|EBV Video]
 +
 
 +
===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.
 +
 
 +
 
 +
{{{{&lt;div id="ensembleEmbeddedContent_'''{YOUR CONTENT ID}'''" class="ensembleEmbeddedContent" style="width: 640px; height: 390px;"&gt;<br />
 +
:&lt;script type="text/javascript" src="'''{YOUR ENSEMBLE SERVER}'''/app/plugin/plugin.aspx?<br />contentID='''{YOUR CONTENT ID}'''&useIFrame=true&embed=true&displayTitle=false&startTime=0&autoPlay=false&<br />hideControls=false&showCaptions=false&width=640&height=360"&gt;&lt;/script&gt;
 +
&lt;/div&gt;}}}}
 +
 
 +
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]
  
  

Revision as of 08:20, 12 October 2012

Contents

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: [1] and [2] (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

http://cloud.ensemblevideo.com/ensemble/app/simpleapi/video/list.xml/4M2akAsn2EGhYH9edW8YSA?resultsCount=10

  1. API Root - http://cloud.ensemblevideo.com/ensemble/app/simpleapi
    Base URL that must be included to start the API call
  2. Data Object - /video
    The type of data you want to return (video or category)
  3. REST Verb - /list
    How you want the data to be returned (list or show)
  4. Return Format - .xml
    What type of data you want to return (XML or JSON(P))
  5. Data ID - /4M2akAsn2EGhYH9edW8YSA
    ID of the web destination or video
  6. API Parameters - ?resultsCount=10
    Parameters for the query. A full list can be found below under [#params|API Parameters].

[anchor|#params]

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:

[3] [4]

Examples

  • Get a list of videos in a particular web site
    [5]
  • Get information for individual video
    [6]
  • Get a list of 10 most recent videos
    [7]
  • Get a list of categories for a web site
    [8]

API Projects

University Video Showcase School Video Showcase (Syracuse University) Video Portal Starter Kit Video

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]


Consult the User's Guide for information on using the wiki software.

Getting started