Media API: Getting Started Using JavaScript

This document presents the basic steps to help you get started making Media API queries from JavaScript. This document assumes that you're familiar with the JavaScript programming language, and that you understand the cross-domain security restrictions that browsers impose on HTTP requests being made in JavaScript. Here are some other docs to review before continuing:

• About XMLHttp object
• Cross-domain security concerns with the XMLHttp object (XML.com)
• Making cross-domain requests with dynamic script tags (XML.com)

Best practices

There are a number of important drawbacks and risks to using JavaScript to access the Media API. Chief among them is token security. With access to your token, a hacker gains access to your library of content and in some cases can play your content without your knowledge. In JavaScript, your token is in plain text in the JavaScript source, an easy target. Server-side usage provides a higher level of security. Read this best practices document on token security for more.

It's also important to consider cross-domain security. The browser policies on cross-domain security make it difficult to implement AJAX applications. The technique we'll use for examples in this section is the dynamic script tag technique, which is described in more detail below.

Lastly, by making JavaScript requests you're missing out on any SEO benefits the Media API offers you to get metadata into your pages. Search engine crawlers don't execute JavaScript code. See this best practices document on SEO with the Media API.

We recommend using a server-side language, like PHP, Java, or ColdFusion, for working with the Media API.

Making requests and parsing results

The easiest way to make a cross-domain HTTP request to the Media API is the dynamic script tag approach. The src attribute of the script tag is not domain-checked by browsers, meaning you can set the src to be a URL on another server, and effectively permit cross-domain communication. However, what comes back from the server when the src is requested must be valid JavaScript. The Media API allows you to specify a "callback" parameter. When you do this, the JSON response is wrapped in a function call, with the name of the function being the value of the callback parameter. For example:

// Make a request like this:
http://api.brightcove.com/services/library?queryparams&callback=response
 
// and the response will be returned as:
// response(... json data ...);
//
// which will invoke a function "response" that you defined in your code

With this approach, the hardest part of making a request is creating the syntax for your call. Then, because the response comes back as native JavaScript objects, the hardest part of handling a response is parsing the results and displaying them according to your site design requirements. The syntax for a Media Read API call looks like this:

<URL>?command=<method_name>&<arguments>=<values>&token=<API_token>

The URL for all Video Cloud Media Read API calls is http://api.brightcove.com/services/library. The URL for all Video Cloud Media Write API calls is http://api.brightcove.com/services/post.

What's Next...

The following documents walk you through some examples to help you get started:

• Media API Examples (JavaScript)
• Top Videos Sidebar Example (JavaScript)
• Upload Video Example (Java)
• Upload Video Example (PHP)