HELIX MEDIA LIBRARY API DEVELOPER S GUIDE

(1)

HELIX MEDIA LIBRARY API – DEVELOPER’S GUIDE

Helix Media Library Version 2.0

(2)

1. Helix Media Library API 1.1 Overview

The Helix Media Library (HML) API (Application Programming Interface) is an extension to the Helix Media Library that allows 3rd parties to communicate with the library in a secure and formal manner. The API consists of a SOAP based web service architecture. The API can be consumed by any 3rd Party that can build a soap reference from a Wsdl.

1.2 How to administrate the API through the GUI

The HML includes a page that can be used to administrate the API. This includes:  _{Turning the API On or Off}

 _{Adding a list of allowed IP Ranges to the API} 1.2.1 Turning the API On or Off

 _{Log into the Upload site of the software using the ‘hmladmin’ user.}  _{Navigate to the Settings Page}

 _{Click ‘API’ at the bottom on the left hand side}  _{Click ‘Enabled’}

 _{Click ‘Save’ – You will see the message “Your changes have been saved successfully.”.}  _{Congratulations – you have now enabled the API, only applications with enabled IP}

address’ (below) will be allowed to call the API. 1.2.2 Adding a list of allowed IP ranges to the API

 _{Log into the Upload site of the HML using the ‘hmladmin’ user.}  _{Navigate to the Settings Page}

 _{Click ‘API’ at the bottom on the left hand side}

 _{Add your IP address to the first empty row in the ‘From’ column..}

 _{If it’s just one IP address then add the same IP in the ‘To’ column. If it’s a range then add}

the last IP address in the range instead.

 _{Click the ‘Enable’ checkbox if you want to enable this range immediately.}

 _{Click ‘Save’ – You will see the message “Your changes have been saved successfully.”.}  _{Congratulations – you have now enabled an IP address, only applications with this IP}

(3)

1.3 Testing a connection to the API 1.3.1 Viewing the WSDL

The API WSDL (Web Service Definition Language) is a metadata file that describes the format of the SOAP packets that must be passed between ‘Server’ (HML API) and ‘Client’ (3rd Party calling application). The file is located on the Upload site of HML. In order to view it navigate to:

<Upload Site Base Url> + /Api/api/hmlapi.svc?wsdl 1.3.2 Connecting the Test Harness

 _{Download the test harness from} http://pam.medialibrary.com/installers/HML-API/TestApi.zip

 _{Unzip it to the required location (where you want to test a connection from [possibly a}

development server]).

 _{Open the file named ‘Test_Api.exe.config’ and change the value for ‘endpoint address’ on}

line 23 to: <Upload Site Base Url> + /Api/api/hmlapi.svc/soap

(4)

 _{Save the file and close it.}

 Now run the file called ‘Test_Api.exe’ you will see a screen in the format: Congratulations – you have now successfully connected a client to the HML API! 1.4 What calls can be made to the API?

 _{GetMediaListing(int mediaId) returns MediaListing}

 _{GetSecureMediaListing(int mediaId, string ipAddress) returns SecureMediaListing}  _{SearchMedia(string keywords, int categoryId, string contributor, string fileName)}

returns Array of MediaListing

 _{GetAllCategories() returns Array of Category}

(5)

2. The API security Model

2.1 What media is returned to a calling application?

When a client connects to the API it does so under the context of the ‘hmladmin’ user. For this reason all calls made will have full privileges and be able to see a top down view of all media within the library. Media can be searched on by Category but it is up to the calling application to decide which media to call and return to its users.

2.2 Can the API use session manager features?

Yes, the 3rd party can make 2 types of calls to the API when it is requesting media. One of them includes a Token with each media item. This token then needs to be put into the URL section of embed code when the media is provided to the user. This will then be sent to the Streaming server, where it will re-connect to the HML and check to make sure that the token is active.

(6)

3.1 Introduction to Embed Code

In terms of embed code for the Media, HML uses the JW Player from http://www.longtailvideo.com

This is used as it provides the ability to failover from Flash to HTML5 so that HML can support Smartphones, Tablets etc as well as PC’s and Mac’s. Below is some sample HTML code populated with values that match with the variables within the HML URL references page below:

3.2 Embed Code Examples: 3.2.1 Video Embed Code Sample

'streamer': 'rtmp://Flash URL Prefix/', 'file': '12345678_hi.mp4',

'image': 'http://Front End URL/thumbnails/12345678.jpg', 'modes': [

{type: 'flash', src: 'http://Front End URL/player58.swf'}, {

type: 'html5', config: {

'file': 'http://Flash URL Prefix/12345678_hi.mp4', 'provider': 'video'

(7)

}, {

type: 'download', config: {

'file': 'http://Flash URL Prefix/12345678_hi.mp4', 'provider': 'video' } } ] }); </script>

3.2.2 Audio Embed Code Example

'file': 'http://Flash URL Prefix/12345678_hi.mp3',

'image': 'http://Front End URL/thumbnails/12345678.jpg', 'modes': [

{type: 'flash', src: 'http://Front End URL/player58.swf'}, {

type: 'html5', config: {

'file': 'http://Flash URL Prefix/12345678_hi.mp3', 'provider': 'video' } }, { type: 'download', config: {

'file': 'http://Flash URL Prefix/12345678_hi.mp3', 'provider': 'video' } } ] }); </script>

4. Use of HML API and Embed Code

Since the HML API exposes media information such as title, description, category and thumbnail URL most integrations concentrate on making the HML content repository searchable from within a third party application with the ability to one-click embed once an item has been selected.

(8)

5. Example integrations 5.1 Helix Media Library Moodle Plugin:

The Helix Media Library repository plugin for Moodle 2.x allows a Helix Media Library content repository to be searched from within Moodle. This means that streaming video and audio content hosted on the Helix video streaming Server can also be easily embedded with a couple of clicks without any technical knowledge.

It works in a very similar fashion to the YouTube file picker, the difference being that the content is securely hosted on your own Helix Server. Since content is hosted on your own streaming server, the issues with hosting video and audio on Moodle itself are avoided and content is streamed back to the end user using the appropriate streaming technology. The Category Association Editor function within the repository plugin also allows for content exclusion from the search by pairing Moodle categories with Helix Media Library categories. Embedded Content can be played back on PC, Mac, iPhone, iPad and Android!

Download Details:http://moodle.org/plugins/view.php?plugin=repository_helix_media_lib Documentation:http://www.helixmedialibrary.net/docs/HML-2_0-Moodle-Module.pdf 5.2 Helix Media Library Blackboard Building Block:

Content Mashup allowing teachers to easily search for and embed video and audio content from their Helix Media Library content repository in course pages. Content is stored securely on the institution's Helix Server and exclusion of content from search is also possible by Course ID. Download Details: http://www.blackboard.com/partnerships/extensions.aspx(search for “Helix Media Library”)

Documentation: http://www.helixmedialibrary.net/docs/HML-2_0-Blackboard-Building-Block.pdf