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