HELIX MEDIA LIBRARY API DEVELOPER S GUIDE

Transcription

1 HELIX MEDIA LIBRARY API DEVELOPER S GUIDE Helix Media Library Version 2.0 Revision Date: August 2015

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 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 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 address will be allowed to call the API. The page should look something like this.

3 1.3 Testing a connection to the API 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 Connecting the Test Harness Download the test harness from 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 For example:

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 The full details of the objects returned by each call can be seen by viewing the WSDL document.

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. 3. Media Embed Code

6 3.1 Introduction to Embed Code In terms of embed code for the Media, HML uses the JW Player from 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: Video Embed Code Sample <script type='text/javascript' src=' End URL/jwplayer.js'></script> <div id='mediaplayer'></div> <script type="text/javascript"> jwplayer('mediaplayer').setup({ 'id': 'playerid', 'width': '320', 'height': '270', 'provider': 'rtmp', 'streamer': 'rtmp://flash URL Prefix/', 'file': ' _hi.mp4', 'image': ' End URL/thumbnails/ jpg', 'modes': [ {type: 'flash', src: ' End URL/player58.swf', { type: 'html5', config: { 'file': ' URL Prefix/ _hi.mp4', 'provider': 'video'

7 , { type: 'download', config: { 'file': ' URL Prefix/ _hi.mp4', 'provider': 'video' ] ); </script> Audio Embed Code Example <script type='text/javascript' src=' End URL/jwplayer.js'></script> <div id='mediaplayer'></div> <script type="text/javascript"> jwplayer('mediaplayer').setup({ 'id': 'playerid', 'width': '320', 'height': '270', 'file': ' URL Prefix/ _hi.mp3', 'image': ' End URL/thumbnails/ jpg', 'modes': [ {type: 'flash', src: ' End URL/player58.swf', { type: 'html5', config: { 'file': ' URL Prefix/ _hi.mp3', 'provider': 'video', { type: 'download', config: { 'file': ' URL Prefix/ _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: Documentation: 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: (search for Helix Media Library ) Documentation: Block.pdf