Using the Netflix API in C#

I got a little side tracked with some other projects, but I finally have some time to post what I’ve discovered about the Netflix API.  There’s a couple of ways to access their movie database.  Depending on what you need will determine which methods will work.  I realized after implementing the Netflix API there’s a simpler method for getting movie information.  Let’s discuss that first.

Go to http://netflixmvp.codeplex.com/ to see all of my source code.

The following is an example of how to make a web request to the OData Catalog API which is the easiest method.  Click here for more examples of how to use this service.  I’m only wanting to filter the results by release year equal to a specific year which is pretty easy.  Since I’m only after the name and boxart, I’ve added a “select” tag for just those fields to be returned.  If you don’t add those, then it returns everything about the movies.  As you can see from the code, the return format is in XML.  I’ve written another method that grabs the boxart URL out of the XML.

// Private Constants
        private const string _ODataTitlesUrl = "http://odata.netflix.com/catalog/Titles?";

        private bool TryGetMovieXMLByReleaseYear(int releaseYear, int? maxNumberOfResults, out string xmlReturnString)
        {
            StringBuilder sb = new StringBuilder(_ODataTitlesUrl);

            // Set the base filter for ReleaseYear
            sb.AppendFormat("$filter=ReleaseYear eq " + releaseYear.ToString());

            // Only return the Name and BoxArt fields
            sb.AppendFormat("&$select=Name,BoxArt");

            // Set the max results
            if (maxNumberOfResults.HasValue && maxNumberOfResults.Value > 0)
                sb.AppendFormat("&$inlinecount=allpages&$top=" + maxNumberOfResults.ToString());

            // Make the request
            try
            {
                WebRequest req = WebRequest.Create(sb.ToString());
                WebResponse rsp = req.GetResponse();
                StreamReader sr = new StreamReader(rsp.GetResponseStream());
                xmlReturnString = sr.ReadToEnd();
                rsp.Close();
            }
            catch (Exception ex)
            {
                xmlReturnString = "Request failed: " + ex.Message + " with URL: " + sb;
                return false;
            }

            return true;
        }

The second method is a little more cumbersome, but offers more features like updating a users queue for example. I did some research on the Internet and found that someone had created a class specifically for talking with an OAuthdatabase. Here is the code for that.

public class OAuthBase
    {

        ///
<summary> /// Provides a predefined set of algorithms that are supported officially by the protocol
 /// </summary>
        public enum SignatureTypes
        {
            HMACSHA1,
            PLAINTEXT,
            RSASHA1
        }

        ///
<summary> /// Provides an internal structure to sort the query parameter
 /// </summary>
        protected class QueryParameter
        {
            private string name = null;
            private string value = null;

            public QueryParameter(string name, string value)
            {
                this.name = name;
                this.value = value;
            }

            public string Name
            {
                get { return name; }
            }

            public string Value
            {
                get { return value; }
            }
        }

        ///
<summary> /// Comparer class used to perform the sorting of the query parameters
 /// </summary>
        protected class QueryParameterComparer : IComparer
        {

            #region IComparer Members

            public int Compare(QueryParameter x, QueryParameter y)
            {
                if (x.Name == y.Name)
                {
                    return string.Compare(x.Value, y.Value);
                }
                else
                {
                    return string.Compare(x.Name, y.Name);
                }
            }

            #endregion
        }

        protected const string OAuthVersion = "1.0";
        protected const string OAuthParameterPrefix = "oauth_";

        //
        // List of know and used oauth parameters' names
        //
        protected const string OAuthConsumerKeyKey = "oauth_consumer_key";
        protected const string OAuthCallbackKey = "oauth_callback";
        protected const string OAuthVersionKey = "oauth_version";
        protected const string OAuthSignatureMethodKey = "oauth_signature_method";
        protected const string OAuthSignatureKey = "oauth_signature";
        protected const string OAuthTimestampKey = "oauth_timestamp";
        protected const string OAuthNonceKey = "oauth_nonce";
        protected const string OAuthTokenKey = "oauth_token";
        protected const string OAuthTokenSecretKey = "oauth_token_secret";

        protected const string HMACSHA1SignatureType = "HMAC-SHA1";
        protected const string PlainTextSignatureType = "PLAINTEXT";
        protected const string RSASHA1SignatureType = "RSA-SHA1";

        protected Random random = new Random();

        protected string unreservedChars = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_.~";

        ///
<summary> /// Helper function to compute a hash value
 /// </summary>
        ///The hashing algoirhtm used. If that algorithm needs some initialization, like HMAC and its derivatives, they should be initialized prior to passing it to this function
        ///The data to hash
        /// a Base64 string of the hash value
        private string ComputeHash(HashAlgorithm hashAlgorithm, string data)
        {
            if (hashAlgorithm == null)
            {
                throw new ArgumentNullException("hashAlgorithm");
            }

            if (string.IsNullOrEmpty(data))
            {
                throw new ArgumentNullException("data");
            }

            byte[] dataBuffer = System.Text.Encoding.ASCII.GetBytes(data);
            byte[] hashBytes = hashAlgorithm.ComputeHash(dataBuffer);

            return Convert.ToBase64String(hashBytes);
        }

        ///
<summary> /// Internal function to cut out all non oauth query string parameters (all parameters not begining with "oauth_")
 /// </summary>
        ///The query string part of the Url
        /// A list of QueryParameter each containing the parameter name and value
        private List GetQueryParameters(string parameters)
        {
            if (parameters.StartsWith("?"))
            {
                parameters = parameters.Remove(0, 1);
            }

            List result = new List();

            if (!string.IsNullOrEmpty(parameters))
            {
                string[] p = parameters.Split('&');
                foreach (string s in p)
                {
                    if (!string.IsNullOrEmpty(s) && !s.StartsWith(OAuthParameterPrefix))
                    {
                        if (s.IndexOf('=') > -1)
                        {
                            string[] temp = s.Split('=');
                            result.Add(new QueryParameter(temp[0], temp[1]));
                        }
                        else
                        {
                            result.Add(new QueryParameter(s, string.Empty));
                        }
                    }
                }
            }

            return result;
        }

        ///
<summary> /// This is a different Url Encode implementation since the default .NET one outputs the percent encoding in lower case.
 /// While this is not a problem with the percent encoding spec, it is used in upper case throughout OAuth
 /// </summary>
        ///The value to Url encode
        /// Returns a Url encoded string
        protected string UrlEncode(string value)
        {
            StringBuilder result = new StringBuilder();

            foreach (char symbol in value)
            {
                if (unreservedChars.IndexOf(symbol) != -1)
                {
                    result.Append(symbol);
                }
                else
                {
                    result.Append('%' + String.Format("{0:X2}", (int)symbol));
                }
            }

            return result.ToString();
        }

        ///
<summary> /// Normalizes the request parameters according to the spec
 /// </summary>
        ///The list of parameters already sorted
        /// a string representing the normalized parameters
        protected string NormalizeRequestParameters(IList parameters)
        {
            StringBuilder sb = new StringBuilder();
            QueryParameter p = null;
            for (int i = 0; i < parameters.Count; i++)
            {
                p = parameters[i];
                sb.AppendFormat("{0}={1}", p.Name, p.Value);

                if (i < parameters.Count - 1)
                {
                    sb.Append("&");
                }
            }

            return sb.ToString();
        }

        ///
<summary> /// Generate the signature base that is used to produce the signature
 /// </summary>
        ///The full url that needs to be signed including its non OAuth url parameters
        ///The consumer key
        ///The token, if available. If not available pass null or an empty string
        ///The token secret, if available. If not available pass null or an empty string
        ///The http method used. Must be a valid HTTP method verb (POST,GET,PUT, etc)
        ///The signature type. To use the default values use OAuthBase.SignatureTypes.
        /// The signature base
        public string GenerateSignatureBase(Uri url, string consumerKey, string token, string tokenSecret, string httpMethod, string timeStamp, string nonce, string signatureType, out string normalizedUrl, out string normalizedRequestParameters)
        {
            if (token == null)
            {
                token = string.Empty;
            }

            if (tokenSecret == null)
            {
                tokenSecret = string.Empty;
            }

            if (string.IsNullOrEmpty(consumerKey))
            {
                throw new ArgumentNullException("consumerKey");
            }

            if (string.IsNullOrEmpty(httpMethod))
            {
                throw new ArgumentNullException("httpMethod");
            }

            if (string.IsNullOrEmpty(signatureType))
            {
                throw new ArgumentNullException("signatureType");
            }

            normalizedUrl = null;
            normalizedRequestParameters = null;

            List parameters = GetQueryParameters(url.Query);
            parameters.Add(new QueryParameter(OAuthVersionKey, OAuthVersion));
            parameters.Add(new QueryParameter(OAuthNonceKey, nonce));
            parameters.Add(new QueryParameter(OAuthTimestampKey, timeStamp));
            parameters.Add(new QueryParameter(OAuthSignatureMethodKey, signatureType));
            parameters.Add(new QueryParameter(OAuthConsumerKeyKey, consumerKey));

            if (!string.IsNullOrEmpty(token))
            {
                parameters.Add(new QueryParameter(OAuthTokenKey, token));
            }

            parameters.Sort(new QueryParameterComparer());

            normalizedUrl = string.Format("{0}://{1}", url.Scheme, url.Host);
            if (!((url.Scheme == "http" && url.Port == 80) || (url.Scheme == "https" && url.Port == 443)))
            {
                normalizedUrl += ":" + url.Port;
            }
            normalizedUrl += url.AbsolutePath;
            normalizedRequestParameters = NormalizeRequestParameters(parameters);

            StringBuilder signatureBase = new StringBuilder();
            signatureBase.AppendFormat("{0}&", httpMethod.ToUpper());
            signatureBase.AppendFormat("{0}&", UrlEncode(normalizedUrl));
            signatureBase.AppendFormat("{0}", UrlEncode(normalizedRequestParameters));

            return signatureBase.ToString();
        }

        ///
<summary> /// Generate the signature value based on the given signature base and hash algorithm
 /// </summary>
        ///The signature based as produced by the GenerateSignatureBase method or by any other means
        ///The hash algorithm used to perform the hashing. If the hashing algorithm requires initialization or a key it should be set prior to calling this method
        /// A base64 string of the hash value
        public string GenerateSignatureUsingHash(string signatureBase, HashAlgorithm hash)
        {
            return ComputeHash(hash, signatureBase);
        }

        ///
<summary> /// Generates a signature using the HMAC-SHA1 algorithm
 /// </summary>
        ///The full url that needs to be signed including its non OAuth url parameters
        ///The consumer key
        ///The consumer seceret
        ///The token, if available. If not available pass null or an empty string
        ///The token secret, if available. If not available pass null or an empty string
        ///The http method used. Must be a valid HTTP method verb (POST,GET,PUT, etc)
        /// A base64 string of the hash value
        public string GenerateSignature(Uri url, string consumerKey, string consumerSecret, string token, string tokenSecret, string httpMethod, string timeStamp, string nonce, out string normalizedUrl, out string normalizedRequestParameters)
        {
            return GenerateSignature(url, consumerKey, consumerSecret, token, tokenSecret, httpMethod, timeStamp, nonce, SignatureTypes.HMACSHA1, out normalizedUrl, out normalizedRequestParameters);
        }

        ///
<summary> /// Generates a signature using the specified signatureType
 /// </summary>
        ///The full url that needs to be signed including its non OAuth url parameters
        ///The consumer key
        ///The consumer seceret
        ///The token, if available. If not available pass null or an empty string
        ///The token secret, if available. If not available pass null or an empty string
        ///The http method used. Must be a valid HTTP method verb (POST,GET,PUT, etc)
        ///The type of signature to use
        /// A base64 string of the hash value
        public string GenerateSignature(Uri url, string consumerKey, string consumerSecret, string token, string tokenSecret, string httpMethod, string timeStamp, string nonce, SignatureTypes signatureType, out string normalizedUrl, out string normalizedRequestParameters)
        {
            normalizedUrl = null;
            normalizedRequestParameters = null;

            switch (signatureType)
            {
                //case SignatureTypes.PLAINTEXT:
                //    return HttpUtility.UrlEncode(string.Format("{0}&{1}", consumerSecret, tokenSecret));
                case SignatureTypes.HMACSHA1:
                    string signatureBase = GenerateSignatureBase(url, consumerKey, token, tokenSecret, httpMethod, timeStamp, nonce, HMACSHA1SignatureType, out normalizedUrl, out normalizedRequestParameters);

                    HMACSHA1 hmacsha1 = new HMACSHA1();
                    hmacsha1.Key = Encoding.ASCII.GetBytes(string.Format("{0}&{1}", UrlEncode(consumerSecret), string.IsNullOrEmpty(tokenSecret) ? "" : UrlEncode(tokenSecret)));

                    return GenerateSignatureUsingHash(signatureBase, hmacsha1);
                case SignatureTypes.RSASHA1:
                    throw new NotImplementedException();
                default:
                    throw new ArgumentException("Unknown signature type", "signatureType");
            }
        }

        ///
<summary> /// Generate the timestamp for the signature
 /// </summary>
        ///
        public virtual string GenerateTimeStamp()
        {
            // Default implementation of UNIX time of the current UTC time
            TimeSpan ts = DateTime.UtcNow - new DateTime(1970, 1, 1, 0, 0, 0, 0);
            return Convert.ToInt64(ts.TotalSeconds).ToString();
        }

        ///
<summary> /// Generate a nonce
 /// </summary>
        ///
        public virtual string GenerateNonce()
        {
            // Just a simple implementation of a random number between 123400 and 9999999
            return random.Next(123400, 9999999).ToString();
        }

    }

Next, I wrote a service method that uses that class to get the information for a specific movie title. One important note about this that I realized is that you must generate the signature and encode AFTER you add the search terms and max results. In other words, you have to build the entire Uri string.

///
<summary> /// This method uses the OAuth class for communication with the NetFlix API using Open Authorization
 /// </summary>
        private string GetMovieXMLInformationUsingOAuth(string movieTitle, string consumerKey, string consumerSecret, int? maxResults)
        {
            // Search Terms must be set here with URI since it's needed to encode the sig
            string uriString = "http://api.netflix.com/catalog/titles?";

            // Add Max results
            if (maxResults.HasValue)
                uriString += "max_results=" + maxResults.ToString();

            // Add title if it exists
            if (!String.IsNullOrEmpty(movieTitle))
                uriString += "&term=" + movieTitle;
            else
                return String.Empty;

            // outputs
            OAuthBase oAuth = new OAuthBase();
            Uri uri = new Uri(uriString);

            string nonce = oAuth.GenerateNonce();
            string timeStamp = oAuth.GenerateTimeStamp();
            string normalizedUrl;
            string normalizedRequestParameters;
            string sig = oAuth.GenerateSignature(uri, consumerKey, consumerSecret, string.Empty, string.Empty, "GET", timeStamp, nonce, OAuthBase.SignatureTypes.HMACSHA1, out normalizedUrl, out normalizedRequestParameters);
            sig = HttpUtility.UrlEncode(sig);

            StringBuilder sb = new StringBuilder(uri.ToString());
            //sb.AppendFormat("term={0}&", "bob");
            //sb.AppendFormat("max_results={0}&", "10");
            sb.AppendFormat("&oauth_consumer_key={0}&", consumerKey);
            sb.AppendFormat("oauth_nonce={0}&", nonce);
            sb.AppendFormat("oauth_timestamp={0}&", timeStamp);
            sb.AppendFormat("oauth_signature_method={0}&", "HMAC-SHA1");
            sb.AppendFormat("oauth_version={0}&", "1.0");
            sb.AppendFormat("oauth_signature={0}", sig);

            // Make the request
            string results = "";
            try
            {
                WebRequest req = WebRequest.Create(sb.ToString());
                WebResponse rsp = req.GetResponse();
                StreamReader sr = new StreamReader(rsp.GetResponseStream());
                results = sr.ReadToEnd();
                rsp.Close();
            }
            catch (Exception ex)
            {
                return "Request failed: " + ex.Message + " with URL: " + sb;
            }

            // Set results in text window
            return results;
        }
        ///
<summary> /// Generate the timestamp for the signature
 /// </summary>
        /// UNIX timestamp
        public virtual string GenerateTimeStamp()
        {
            // Default implementation of UNIX time of the current UTC time
            TimeSpan ts = DateTime.UtcNow - new DateTime(1970, 1, 1, 0, 0, 0, 0);
            return Convert.ToInt64(ts.TotalSeconds).ToString();
        }

        protected Random random = new Random();

        ///
<summary> /// Generate a nonce
 /// </summary>
        /// Nonce value
        public virtual string GenerateNonce()
        {
            // Just a simple implementation of a random number between 123400 and 9999999
            return random.Next(123400, 9999999).ToString();
        }

Here’s the developer reference page from Netflix that explains how to use this service.

Netflix Movie App

There’s hasn’t been much going on at work lately, so I thought I’d spend some time learning something new.  For me to “play” with something new, I need something interesting to code for which is where Netflix comes into play.  I discovered the Netflix API which allows anyone to access their database of movie information.  You can access the data from several different ways depending on what kind of information you need.  You have the power to access & modify your movie queue or just get information about movies like descriptions, actors, release dates, etc.

I think I’m going to work towards writing an app using the MVP pattern for a Windows Form and WPF UI that shows movie box art.  I’m pretty familiar with both, but I figure I can use the application as a starting place to learn other languages that I’m less familiar with.