ActionScript wrapper for the Brightcove Media APIs

Brightcove has made some big strides in opening up their online service to developers in the last few years.  In particular, the Brightcove Media API, a JSON-based read and write API for interacting with the Brightcove platform, is a powerful tool for online experience development.

Developers who want to assemble customized online experiences can access the media libraries created by publishers and define custom visual experiences with really no limit.  Even though this is JSON-based, access to the Media APIs is not limited to AJAX clients. ActionScript clients as well have the full wealth of the Brightcove Media API at their disposal.

Let’s start by looking at a simple example application which loads a set of videos from the Brightcove Media APIs and populates them in a datagrid.

Before:  Example Application – Loading a Datagrid with Brightcove Videos

As is available in the documentation, the below application provides a fairly straight-forward approach to loading videos:

  • Construct the proper HTTP request and define a listener
  • In the result handler, parse the JSON results into ActionScript Objects
  • Populate a datagrid with the results
 
< ?xml version="1.0" encoding="utf-8"?>
<mx:application xmlns:mx="http://www.adobe.com/2006/mxml">
    
    <!--
        ********************************************************************************************
        SCRIPT
        ********************************************************************************************
    -->
    <mx:script>
    < ![CDATA[
        import com.adobe.serialization.json.JSON;
        import mx.collections.ArrayCollection;
        import mx.controls.Alert;

        /** The object used to load URLs */
        private var _loader:URLLoader;
        
        /** The path to the brightcove api services */
        private const BRIGHTCOVE_API_PATH:String = "http://api.brightcove.com/services/library";
        
        /** The publisher token to be used to make the requests */
        private var _token:String = "0Z2dtxTdJAxtbZ-d0U7Bhio2V1Rhr5Iafl5FFtDPY8E."
        
        /** The command string to find all videos*/
        private const FIND_ALL_COMMAND_STRING:String = "find_all_videos";
        
        /** 
         * The "click" event listener for the find_all_videos button - load the videos from 
         * Brightcove convert them for JSON to native AS Objects and populate it in a datagrid
         */  
        private function onButtonClick():void {

            var url:String = BRIGHTCOVE_API_PATH + 
                "?command=" + 
                FIND_ALL_COMMAND_STRING +
                "&token=" +
                _token;

            trace('url to request: ' + url);
            var request:URLRequest = new URLRequest(url);
             
            _loader = new URLLoader();
            _loader.addEventListener(IOErrorEvent.IO_ERROR, errorHandler);
            _loader.addEventListener(Event.COMPLETE, loaderCompleteHandler);
             
            try {
                _loader.load(request);
            }
            catch (error:SecurityError) {
                trace("A SecurityError has occurred.");
            }
        
        }
        
        /** "fault" event listener to the remote call to the Brightcove media APIs */ 
        private function errorHandler(event:Event):void {
        
           mx.controls.Alert.show(
              "An error occurred" + 
                  event.target.toString(),
              "An error occurred");
        
        }
            
        /** "result" event listener to the remote call to the Brightcove media APIs */ 
        private function loaderCompleteHandler(event:Event):void {
            
            //Get the returned JSON data string
            var response:String = event.target.data as String;
         
            //The list of returned videos is embedded in the "items" property
            //of the root JSON object, so we will decode to a container
            var container:Object = (JSON.decode(response) as Object);
         
            videosDataGrid.dataProvider = new ArrayCollection(container.items);

            //Convert the UNIX date into an AS3 Date
            for(var i:int = 0; i< videosDataGrid.dataProvider.length; i++) {
                var video:Object = videosDataGrid.dataProvider.getItemAt(i);
                var n:Number = video.publishedDate;
                video.publishedDate = new Date(n);
            }           
         
        }

    ]]>
    </mx:script>
    
    <!--
    	********************************************************************************************
    	VIEW
    	********************************************************************************************
    -->
    <mx:button id="loadButton"
        label="Load Vidoes"
        click="onButtonClick()"/>
    
    <mx:datagrid id="videosDataGrid"
            width="100%" height="100%">
           
        <mx:columns>
            <mx:datagridcolumn dataField="id" 
                headerText="ID"/>
            <mx:datagridcolumn dataField="name" 
                headerText="Name"/>
            <mx:datagridcolumn dataField="shortDescription" 
                headerText="Description"/>
            <mx:datagridcolumn dataField="publishedDate" 
                headerText="Published Date"/>
        </mx:columns>
    </mx:datagrid>

</mx:application>

Room for Improvement

Although the above is a good start, there are many areas of improvement. 

In particular:

  • It is too low-level.  In the application we need to concern ourselves with JSON parsing, handling flash security exceptions, and constructing the exact request variables that the Brightcove Media API requires.  We need to create a layer of abstractions above all of this, so the Views interacting with BC have a nice clean high-level interface they are working with. Such other concerns can be seperated away and handled by objects specifically responsible for them.
  • It isn’t very typesafe.  Basically, if a fault is returned from the server, it will be returned as a JSON object with the fault information included in the payload.  Ideally, we would have access to typesafe success and fault objects when interacting with the BC Media API.
  • It’s verbose.  It contains over lines and 3 functions.  For an application that makes heavy use of the BC Media APIs this code will need to be refactored almost immediately to re-use common request and response handling.
  • It isn’t self-documenting and not very Object-Oriented.  For example, most developers will be unware of different fault conditions that can be returned from the server until they are encountered at run-time, or possibly researched in some online documentation.  It would be great if these faults were defined in the code somewhere. Additionally, it would be cleaner if constructing requests is done purely with type-safe intuitive objects, rather than esoteric request Strings.

After the refactoring
The below code, is the example application after it has been refactored to use a Brightcove Media API wrapper.  It cleans up the client code and frees ActionScript developers to work at a higher, more spacious level of abstraction

< ?xml version="1.0" encoding="utf-8"?>
<mx:application xmlns:mx="http://www.adobe.com/2006/mxml">
    
    <!--
        ********************************************************************************************
        SCRIPT
        ********************************************************************************************
    -->
    <mx:script>
    < ![CDATA[
        import com.allenmanning.brightaction.api.MediaRequestErrorType;
        import mx.controls.Alert;
        import mx.collections.ArrayCollection;
        import com.allenmanning.brightaction.api.MediaRequestType;
        import com.allenmanning.brightaction.api.MediaRequest;

        /** The publisher token to be used to make the requests */
        private var _token:String = "0Z2dtxTdJAxtbZ-d0U7Bhio2V1Rhr5Iafl5FFtDPY8E."
        
        /** 
         * The "click" event listener for the find_all_videos button - work with the MediaRequest
         * Object to construct a "load videos" request, and register event listeners for handling
         * the response.
         */  
        private function onButtonClick():void {

            var mediaRequest:MediaRequest = new MediaRequest(
                _token,
                MediaRequestType.FIND_ALL_VIDEOS);

            mediaRequest.addEventListener(
                MediaRequest.RESULT_NAME,
                function():void {
                    videosDataGrid.dataProvider = mediaRequest.resultData;
                }
            );

            mediaRequest.addEventListener(
                MediaRequest.FAULT_NAME,
                function():void {

                    //tyepsafe error checking, no knowledge of BC Media API Error codes here
                    if(mediaRequest.error.errorType() == MediaRequestErrorType.INVALID_TOKEN) {
                        Alert.show("This token is not valid");
                    } else {
                        Alert.show(mediaRequest.error.errorType().toString());
                    }
                    
                }
            );

            mediaRequest.execute();
        
        }
        
   ]]>
    </mx:script>
    
    <!--
    	********************************************************************************************
    	VIEW
    	********************************************************************************************
    -->
    <mx:button id="loadButton"
        label="Load Vidoes"
        click="onButtonClick()"/>
    
    <mx:datagrid id="videosDataGrid"
            width="100%" height="100%">
           
        <mx:columns>
            <mx:datagridcolumn dataField="id" 
                headerText="ID"/>
            <mx:datagridcolumn dataField="name" 
                headerText="Name"/>
            <mx:datagridcolumn dataField="shortDescription" 
                headerText="Description"/>
            <mx:datagridcolumn dataField="publishedDate" 
                headerText="Published Date"/>
        </mx:columns>
    </mx:datagrid>

</mx:application>

In this application we have pushed the concerns of the API interaction down into the MediaRequest Object. The View is only responsible with interacting with with this wrapper or Remote Proxy.

Let’s look at a couple techniques being used here:


Typesafe and simplified error handling

The below code snippet is from MediaRequest, the object is responsible for knowing how to interact with Brightcove and parse the results. Additionally, all errors, remote faults and also client-side security exceptions are treated as being the same. It makes the interaction with the client cleaner, because there is only one type of fault to listen for.

The Media Request Object, also interacts with a collaborator: MediaRequestError. This Error object is responsible for storing all errors, client-side or server-side. All of these errors and registered, documented, with the understandable MediaRequestErrorType.

	  	//------------------------------------------------------------------------------------------
		// Methods
		//------------------------------------------------------------------------------------------
	    /** 
	     * Execute the Brightcove Media API asynchronous request for the token based upon the given 
	     * Media Request type.  
	     * 
	     * If a result has been returned, populate this object with the result converted into native
	     * AS3 objects, not JSON, and dispatch an event notifing listeners of this object that the 
	     * request has been completed.
	     * 
	     * If a fault has been returned, store the fault in this object and dispatch a Fault event 
	     * notifying listeners that a fault has occured.
	     */
	    public function execute():void {
	        
	        // initilize existing result data
	        _resultData = null;
            _error = null;
            	    
            var url:String = BRIGHTCOVE_API_PATH + 
                "?command=" + 
                _requestType.toString() +
                "&token=" +
                _readToken;

            var request:URLRequest = new URLRequest(url);

            _loader = new URLLoader();
            _loader.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);
            _loader.addEventListener(Event.COMPLETE, loaderCompleteHandler);
             
            try {
                _loader.load(request);
            } catch (error:SecurityError) {
                handleErrors(
                    new MediaRequestError(
                        MediaRequestErrorType.FLASH_SECURITY_ERROR, 
                        error));
            }

	    }

        /** Construct an error object and dispatch a fault event */
        private function handleErrors(error:MediaRequestError):void {
            
            _error = error;
            dispatchEvent(new Event(MediaRequest.FAULT_NAME));
        
        }
        
        /** "fault" event listener to the remote call to the Brightcove media APIs */ 
        private function ioErrorHandler(event:Event):void {

            handleErrors(new MediaRequestError(MediaRequestErrorType.IO_ERROR, event));
                    
        }
        
        /**
         * Return true if the result of the call should be considerd a fault, false otherwise
         * 
         * @param result    the media API result as an ActionScript object
         */
        private function checkAndSetFault(result:Object):void {
            
            if(MediaRequestError.hasError(result)) {
                
                handleErrors(MediaRequestError.createFromResponse(result));
                
            }
            
        }
            
        /** "result" event listener to the remote call to the Brightcove media APIs */ 
        private function loaderCompleteHandler(event:Event):void {
            
            //Get the returned JSON data string
            var response:String = event.target.data as String;
         
            //The list of returned videos is embedded in the "items" property
            //of the root JSON object, so we will decode to a container
            
            //TODO Make the JSON decoding pluggable
            var result:Object = (JSON.decode(response) as Object);
            
            checkAndSetFault(result);

            if(_error != null) {
                return;
            }
            
            _resultData = new ArrayCollection(result.items);

            //Convert the UNIX date into an AS3 Date
            for(var i:int = 0; i< _resultData.length; i++) {

                var video:Object = _resultData.getItemAt(i);
                var n:Number = video.publishedDate;
                video.publishedDate = new Date(n);

            }           
         
            dispatchEvent(new Event(MediaRequest.RESULT_NAME));
        
        }


Self Documenting and Typesafe Error Handling with an AS “Enumeration”

Rather than sprinkling error parsing and checking code throughout our Brightcove ActionScript applications, defining them in a typesafe enum is a cleaner and more centralized place to document these conditions and lets other objects work with how they should be handled.

Without real Enum support, we define a set of static constants which are themselves instances a of the MediaRequestErrorType. This object defines a fault name and also registers and associated Error Code (if applicable).

The getErrorForCode() method lets us return a unqiue ErrorType object for a given error code. By using this registration-based approach, we have avoided any long conditional or awkward switch statements. As new errors are discovered, they are simply registered with this object, in a single location.

package com.allenmanning.brightaction.api {
 
    /**
     * An enumeration modeling the different types of Media Requests Errors
     * 
     * @author amanning
     */
    public class MediaRequestErrorType {

        //------------------------------------------------------------------------------------------
        // Member variables
        //------------------------------------------------------------------------------------------
        // Invalid Token was passed to the Media APIs
        public static const INVALID_TOKEN:MediaRequestErrorType = 
            MediaRequestErrorType.createAndRegister("INVALID_TOKEN", 210);

        // Request Validation Errors
        public static const VALIDATION_ERROR:MediaRequestErrorType = 
            MediaRequestErrorType.createAndRegister("VALIDATION_ERROR", 301);

        // Flash Communication Security Error
        public static const FLASH_SECURITY_ERROR:MediaRequestErrorType = 
            MediaRequestErrorType.createAndRegister("FLASH_SECURITY_ERROR");

        // IO Error, a problem with issuing the HTTP Get request to the media API
        public static const IO_ERROR:MediaRequestErrorType = 
            MediaRequestErrorType.createAndRegister("IO_ERROR");

        // Unknown Error, either not mapped into this wrapper API, or not invalid construction on 
        // the server
        public static const UNKNOWN_ERROR:MediaRequestErrorType = 
            MediaRequestErrorType.createAndRegister("UNKNOWN_ERROR");
        
        /** The toString value for the enum */
        private var _value:String;
        
        /** Return a string representation of this type */
        public function toString():String {
        
            return _value;
        
        }

        /** The error code associated with the error, if any */
        private var _code:Number;
        
        public function code():Number {
        
            return _code;
        
        }
        
        /** A look-up table for all of the codes, this gets initialized in the class constructor */
        private static var _codeLookupTable:Object;

        //------------------------------------------------------------------------------------------
        // Constructors
        //------------------------------------------------------------------------------------------
        /**
         * Class constructor - initialize the string representation of this enum
         * 
         * @param value     The string representation of this enum
         * @param code      An associated error code, if any
         */ 
        function MediaRequestErrorType(value:String,code:Number=-1) {
        
            _value = value;
            _code = code;
            
        }
        
        //------------------------------------------------------------------------------------------
        // Methods
        //------------------------------------------------------------------------------------------
        
        /**
         * Given a value and a code, create an error type and register it with the error lookup 
         * table
         * 
         * @param value     The string representation of this enum
         * @param code      An associated error code, if any
         * @return          Registered Media Request Error type
         */
        public static function createAndRegister(
                value:String,
                code:Number=-1):MediaRequestErrorType {
        
            var errorType:MediaRequestErrorType = new MediaRequestErrorType(value,code);
            
            if(_codeLookupTable == null) {
                _codeLookupTable = new Object();
            }
            
            if(errorType.code() != -1 && !_codeLookupTable.hasOwnProperty(code)) {

                _codeLookupTable[code] = errorType;
            
            }
            
            return errorType;
            
        }
        
        /**
         * Given an error code, return the corresponding ErrorType object, if it exists, or null 
         * otherwise
         * 
         * @param code  the error code to look up
         * @return      the corresponding ErrorType object, if it exists, or null otherwise
         */
        public static function getErrorForCode(code:Number):MediaRequestErrorType {
            
            if(_codeLookupTable.hasOwnProperty(code)) {
            
                return _codeLookupTable[code];
            
            }
 
            return null;
        
        }
    
    }   

}

Where to go from here?
A working example of this can be downloaded here, along with a set of Flexunit tests supporting this wrapper.

This is just the beginning, there are many places to go from here:

  • Support for all read and write operations
  • Pluggable JSON parsing
  • Automatic AS de-serialization