The simple API is a REST based web service implementation for retrieving data from the application. It is used internally by Quick Publish feature but it is also 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, JSON (Java Script Object Notation) and RSS (Real Simple Syndication). The first version of the API supports several features:

• Listing videos in a particular web site. This includes video metadata and related thumnails so a video list can be created and showed on an external web sites.
• Showing invidividual video information. This includes all video metadata, previews/thumnails, 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 convetion 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 individuatl record such an invididual video record

Possible Implementations

Since the API can return data in XML, JSON or RSS, 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

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 paramters. Therefore, a call to the API can be broken into several parts. Let's look at an example:

simpleapi/category/list.xml/AB91348D-5F7B-49DA-A237-4BE383E32367

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", "json" and "rss"

AB91348D-5F7B-49DA-A237-4BE383E32367 - The primary key for the type of records you want to return. In this case this returns to the web site id.

The above call can also be made as follows by using query parameters:

simpleapi/category/list.xml?webSiteID=AB91348D-5F7B-49DA-A237-4BE383E32367

Note: GUID values are used when referencing primary keys such as video IDs or web site IDs. However, the API also supports using a "Short GUID". There is a utility function that will return a "Short GUID" based on a GUID and vice versa. So the above call is equvalant to something like:

simpleapi/category/list.xml/jTSRq3tf2kmiN0vjg-MjZw

API Parameters

Individual paramters or a combination of paramters can be used when quering 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 Convetion) so the ID paramters (such as videoID, categoryID and webSiteID) do not need to be exclusevly specified:

simpleapi/video/show.xml/ZCCpNouPKk6BAg6hYYALhA

is the same as

simpleapi/video/show.xml?videoID=ZCCpNouPKk6BAg6hYYALhA

Here is the list of paramters and a definition for each:

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 paramters will be ignored.

orderByDirection

The order direction to be used in combination with the "orderBy" paramter.

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" paramter.

resultsCount

The number of results to return.

searchString

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

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=videoTitle&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=00A69DF0-2988-49E5-A635-22C59916CEC5
   
• 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=1

More Examples

----------------
video
----------------
- With Short Guid
simpleapi/video/show.xml/ZCCpNouPKk6BAg6hYYALhA
- With Guid
simpleapi/video/show.xml/36a92064-8f8b-4e2a-8102-0ea161800b84

---------
With Query Parameters
---------
- With Short Guid
simpleapi/video/show.xml?videoid=ZCCpNouPKk6BAg6hYYALhA
- With Guid
simpleapi/video/show.xml?videoid=36a92064-8f8b-4e2a-8102-0ea161800b84
--------------------------------
--------------------------------
----------------
category
----------------
- With Short Guid
simpleapi/category/list.xml/jTSRq3tf2kmiN0vjg-MjZw
- With Guid
simpleapi/category/list.xml/AB91348D-5F7B-49DA-A237-4BE383E32367

---------
With Query Parameters
---------
- With Short Guid
simpleapi/category/list.xml?websiteid=jTSRq3tf2kmiN0vjg-MjZw
- With Guid
simpleapi/category/list.xml?websiteid=AB91348D-5F7B-49DA-A237-4BE383E32367
--------------------------------
--------------------------------
----------------
videos
----------------
- With Short Guid
simpleapi/video/list.xml/jTSRq3tf2kmiN0vjg-MjZw
- With Guid
simpleapi/video/list.xml/AB91348D-5F7B-49DA-A237-4BE383E32367

---------
With Query Parameters
---------
- With Short Guid
simpleapi/video/list.xml?websiteid=jTSRq3tf2kmiN0vjg-MjZw
- With Guid
simpleapi/video/list.xml?websiteid=AB91348D-5F7B-49DA-A237-4BE383E32367