SOAP API

The MEDIAL API allows third-party applications to communicate with the media library securely to perform actions such as searching for specific content or listing all media. Using this API, you can build a SOAP (Simple Object Access Protocol) reference from a WSDL (Web Service Definition Language).

Enabling and Securing the API

Use the API page to define the range of IP addresses that can connect to the MEDIAL API. An application using the API connects as the media library administrator hmladmin. The account password is not required because the specified IP address range enforces security. All API calls have full media library privileges and are able to see a top-down view of media within the library. The API can search for media by category, but it is up to the application calling the API to determine which media to return to its users.

Session Manager

A third-party application can make two types of calls to request media. The first type includes a token with each media item. This token must be placed in the URL section of the embed code when the media is provided to the user. When the media is played, a token like the one shown in the following example will be sent to the streaming server, which checks with the media library to ensure that the token is still valid:

rtmp://stream.domain.com/flash/mp4:12345678_hi.mp4?token=(58909824)

See the topic Session Manager.

Testing the API

The API WSDL is a metadata file that describes the format of the SOAP packets that pass between the server that handles the API and the third-party client that calls the API. To view it, navigate to the following address on the MEDIAL upload site:

Back_End_URL/Api/hmlapi.svc?wsdl

For example:

http://upload.medialibrary.com/Api/hmlapi.svc?wsdl

For the base URL, use the MEDIAL Back End URL value found in the URL References.

API Calls

The following are the API calls that a third-party application may make. The WSDL document provides details about the objects returned by each call.

SOAP APIs and Return Values
API Call	Variables	Return Value
GetMediaListing	int mediaId	MediaListing
GetSecureMediaListing	int mediaId, string ipAddress	SecureMediaListing
SearchMedia	string keywords, int categoryId, string contributor, string fileName	MediaListing array
GetAllCategories	null	Category array

Using the Test Harness

The test harness is a Windows executable that checks whether a connection can be made to the MEDIAL API and whether information can be returned. It is recommended that you run the test harness from a development machine that is allowed to connect to the MEDIAL API before you integrate the API with a third-party application.

To run the test harness:

Download the test harness Zip archive from http://pam.medialibrary.com/installers/HML-API/TestApi.zip.
Unzip the files in the location on your development server where you want to test the connection. The Test API utility contains four files:
Using a text editor, open one of the following depending on the MEDIAL setup:
- https off.config if MEDIAL uses standard HTTP.
- https on.config if MEDIAL uses secure HTTP (HTTPS).
If you are running the MEDIAL sites over HTTPS, you may need to change the upload site’s web.config file to allow the API to connect. For instructions on how to do this, see the support article How to Configure the API to Work Over HTTPS.

The URL References indicate if HTTP or HTTP is in use.
Select the entire contents of the file and copy it to the clipboard.
Open the file named Test_Api.exe.config in your text editor and paste the contents of the clipboard, replacing everything in the existing file.
Locate endpoint address on line 23.
Change the value to the following:
```
Back_End_URL/Api/hmlapi.svc/soap
```
For example:
```
https://upload.medialibrary.com/Api/HmlApi.svc/soap  
```
For the MEDIAL base URL, use the Back End URL value found in your MEDIAL URL References.
Save the file and close it.
Open a Windows command prompt, navigate to the test harness directory, and run the Test_Api.exe program. If the connection works, the command prompt window displays a success message:
The Test API tool next lists the values it is able to return from the media library, finishing with an END message:

Media Embed Code

For embed code, MEDIAL uses JW Player (http://www.jwplayer.com), which provides failover from Flash to HTML5 so that MEDIAL can support smartphones and tablets as well as PCs and Mac computers. The following sections provide sample video and audio HTML embed code populated with values that match the sample URL References illustrated here:

Because the API exposes media information such as title, description, category, and thumbnail URL, most integrations make the content repository searchable from within a third-party application, adding the ability to one-click embed a selected item.

Video Embed Code Sample

<script type='text/javascript' src='https://media.domain.com Use the Front End URL value from the URL References./jwplayer.js'></script>

<div id='mediaplayer'></div>

<script type="text/javascript">
  jwplayer('player').setup({
     autostart: 'false', 
     allowfullscreen: 'true', 
     width: '640', 
     height: '385', 
     image: 'https://media.domain.com Use the Front End URL value from the URL References./thumbnails/12345678.jpg?v=1', 
     abouttext: Video Clip, 
     base: 'https://media.domain.com Use the Front End URL value from the URL References./jwplayer6/', 
     fallback: 'false', 
     primary: 'flash', 
     sources: [{ file: 'rtmp://stream.domain.com/flash Use the Flash URL Prefix value from the URL References./mp4:12345678_hi.mp4?token=(58909824)' }, 
       { file: 'http://stream.domain.com/flash Use an HTTP protocol with the Flash URL Prefix from the URL References./12345678_hi.mp4?token=(58909824)' }]
  });
</script>

Audio Embed Code Example

<script type='text/javascript' src='https://media.domain.com Use the Front End URL value from the URL References./jwplayer.js'></script>

<div id='mediaplayer'></div>

<script type="text/javascript">
  jwplayer('player').setup({
     autostart: 'false', 
     allowfullscreen: 'true', 
     width: '640', 
     height: '385', 
     image: 'https://media.domain.com Use the Front End URL value from the URL References./thumbnails/cats/1.jpg', 
     abouttext: 'Audio Clip', 
     base: 'https://media.domain.com Use the Front End URL value from the URL References./jwplayer6/', 
     fallback: 'false', 
     primary: 'flash', 
     sources: [{ file: 'rtmp://stream.domain.com/flash Use the Flash URL Prefix value from the URL References./mp3:87654321_hi.mp3?token=(12016218)' }, 
       { file: 'http://stream.domain.com/flash Use an HTTP protocol with the Flash URL Prefix from the URL References./87654321_hi.mp3?token=(12016218)' }]
  });
</script>