Getting Started with the Media API

This document provides an overview of the Video Cloud Media API.

The Media API is a REST-based API for accessing the content and metadata in your Video Cloud account. Because the Media API is a REST-based API, it can be accessed from a wide variety of places in your web applications, not just on the client, but in your dynamically-generated web pages or server-side synchronization processes, for example.

To prevent unauthorized access to the metadata in your account, Video Cloud protects access to the API with tokens that you pass as parameters when making API calls. Like other web-based APIs, tokens are generated for you by Video Cloud and protected by you.

The first thing you need to do to get started is to get the tokens for your account. The Media API is not available to Video Cloud Express Plan I or II customers. Read tokens for the Media API's read methods are available to Video Cloud Express Plan III customers, and the full Media API is available to Video Cloud Pro and Enterprise customers.

In this overview, you will get familiar with the Media API and learn about:

Under the hood of the Media API

REST, or Representational State Transfer, is a standard way of accessing data stored in a remote system over HTTP. It is a cousin of SOAP and is one of the technologies that power web services. Its primary ability is to abstract the workings of the remote system in the transfer of its state (or information). All your code needs to understand is the format of the data that is sent back.

The Media API includes read and write methods.

  • The Read API consists of a set of methods that perform a variety of queries on our servers (which are cached for performance), and return sets of data in DTOs or Data Transfer Objects. For example, one API method is find_all_videos, which returns a list of VideoDTOs, where each VideoDTO contains the metadata for a specific video. The return data is formatted as either JSON strings or as MRSS-formatted XML. JSON (JavaScript Object Notation) is a lightweight way of transferring complex objects as strings, and nearly every language today can claim a large number of publicly available libraries to parse JSON strings into native objects. MRSS (Media Really Simple Syndication) is an RSS module used for syndicating multimedia files (audio, video, image) in RSS feeds.

    Note that URLs for videos and images are subject to change without notice, so you need to pull them dynamically using the Media API when you use them in pages, or if that is not possible, re-run your queries to retrieve them regularly and update links in your pages as needed.

  • The Write API consists of a set of methods that create, update, or delete videos and playlists. For example, one Write API method is create_video, which you can use to pass in a video file, its associated metadata, and create a video in your Video Cloud account. Note that it is possible to restrict Media API tokens so that only specified Media API methods may be called. For more information, see Restricting Access to Media API Write Tokens.

Calling Media API methods

Method calls using REST are basically HTTP GET requests (for read methods) or POST requests (for write methods) to a particular URL on the Video Cloud servers. The request includes the name of the method you're calling, together with its input arguments, which are passed as parameters in the URL. The body of the HTTP response contains the results of the HTTP call as a JSON string or as MRSS-formatted XML. All Media API calls use the base URL http://api.brightcove.com/services. Accessing Video Cloud Services through IP addresses is not supported and should be avoided at all times. Video Cloud IP addresses can change at any time without notice; a change can cause any systems trying to access them via IP address to fail.

Important note for Japanese publishers

If you are a customer of Brightcove KK, our Japanese joint venture, you need to use a different URL to access the Media API. All of your Media API calls need to begin with http://api.brightcove.co.jp, and not http://api.brightcove.com.

Method calls also require a token. Video Cloud issues tokens to accounts; tokens give you access to your account when you use the API. There are separate tokens for read methods and write methods in the API. You append your token to the call as a URL parameter, such as token=[tokenString], where tokenString is your URL-encoded token. Note that Media API tokens generally end with one or more dots (.). Be sure to include the dots when you use the API tokens — it's easy to lose them when you cut and paste. You can view and manage your API tokens on the Account Info: Account Settings: API Management page in the Video Cloud Studio, which also provides a button for emailing a token or copying a token to your clipboard. For more information about tokens, see Managing Media API Tokens.

For example, to retrieve all videos in your account, you make an HTTP request that looks like:

http://api.brightcove.com/services/library?command=find_all_videos
&token=0Z2dtxTdJAxtbZ-d0U7Bhio2V1Rhr5Iafl5FFtDPY8E.

This is a working request — you can try it here. You'll quickly see the results of the call print out. This is a raw method call. What comes back is unprocessed and is not formatted. In the examples, you'll see ways to take the returned data and shape it in ways that are useful for an application. (Note: This call uses a demo account. To use your own account, substitute your own read token in the &token argument.)

Incorporating the API into your application

Because Media API requests are simple HTTP calls, you can include them just about anywhere in your application. Every popular language for the web, server- or client-side, has syntax for making HTTP requests. These are what you use to include API calls in your application. In addition, Video Cloud-savvy developers have created SDKs (Software Development Kits) for most popular web-oriented languages that you can include in your applications as native classes for easy API access. Check out Video Cloud SDKs to see an up-to-date list of available Media API SDKs. You should also check out Open Source @ Brightcove, a community supported initiative to host a variety of applications, SDKs and tools for the Video Cloud platform in one central location.

Chances are your request will be made on-demand — for example, when a page loads, when a user clicks a button, or when some other event occurs. To handle this, wrap the HTTP request in a function and call it in response to some programmatic event, like an onClick event. You must also handle the response and, if you're not working in JavaScript, parse the JSON string or MRSS output into native objects so that you can work with the data. Be aware that JSON does not reliably return data in a particular order; we suggest you use a JSON parser to get hold of the fields you want to work with.

With the Write API methods, you can create a client application that integrates your Video Cloud account with your content management system. Or you might write a desktop application that is run locally and doesn't need a server between the client and Video Cloud. Another possible architecture could be one with a Flash client, using Flash's HTTP stack. You could also possibly use Adobe AIR, Adobe's new desktop client, to create a Flash-based desktop uploader application.

API parameters

The basic Read API calls, like find_all_videos, can be refined with additional parameters. The API reference lists the complete set, but here is an overview of just a few of the things you can do:

  • Page the search results. You can opt to return pages of data if you expect a large number of results. You can set the page size and select a specific page to be returned. The maximum page size is generally 100; if you don't set the page size, results will be returned in pages of 100.
  • Select fields for the return set. In most use cases you'll only need specific fields of data, like the name and the shortDescription fields. You can force the API to only return these fields to optimize the call time.
  • Sorting. You can specify a sort order to be applied to the result set, such as alphabetically, creation date, publish date, modified date, last weeks play count, or the total play count.

The basic Write API calls, like create_video, take parameters that add the metadata for the video you're creating. There are also Write API methods to create, update, and delete playlists and to create cue points, images, and logo overlays.

Working with JSON

When you work with JSON strings, make sure you use the appropriate JSON syntax. String values are enclosed in quotes, while numbers and boolean values are not. For example, in the following, create_video, token, and filename are strings, while create_multiple_renditions is a boolean:

{"method": "create_video",
"params": {"token" : "riBfgveLvpRb-rHGiBBouSAXs-Q8NmphGxt0z04kE.",
           "video" : {"id":38,"name":"Cookies!","shortDescription":"yumyumyumyum tasty!"},
           "filename":"miamiMoon.mov",
           "create_multiple_renditions" : true}}

Review the Media API Reference for the correct signature for each method you use, as well as the Media API examples. For more information about JSON, visit json.org.

Caching

To enhance performance, API calls are cached on Video Cloud servers. When a call is made, Video Cloud checks the cache first. If that call hasn't been cached or the cache has expired, the call goes straight to the database and Video Cloud sends the results back and also caches them. The cache expires after 5 minutes. If you make additional calls within that window the results will come from the cache rather than the database.

Caching doesn't take into account changes you may make to your library using the Video Cloud Studio or batch upload. Changes made to your library that would affect a call won't be reflected in the call's results until the cache expires. Keep this in mind when you are testing your code; the API may be working correctly, even if you're not seeing the correct results.

Error handling

The API will try to catch common errors, such as a video_id that doesn't exist, and handle them in a code-friendly way. Most errors are returned as JSON strings with an error parameter like this:

{"error": "an unknown error occurred while processing your request ","code":100}

If your output is MRSS, errors are included in an <error> element that includes an error code and message.

As much as you can, your code should always try and handle errors gracefully, as opposed to having the end-user deal with a cryptic message or blank page. By handling the "error" parameter of the result object (after JSON-parsing the response), you will know what might have gone wrong so that you act on it appropriately by programming an error message for the end-user.

Error messages returned by the Media API include a numerical error code that classifies errors by type. For more information, see the Error Message Reference.

Token management and security

Keep your token secure — it provides access to your library. This is especially important if you're considering client-side API calls. Any of your web visitors can "view source" and see your API token, which they could then use to retrieve your metadata, including, potentially, direct links to your assets.

Read Media API: Security Best Practices for more details and strategies to keep your token secure.

Note that it is possible to restrict Media API tokens so that only specified Media API methods may be called. For more information, see Restricting Access to Media API Write Tokens.

Limitations of the Media API

In general, anything you can do with a video or playlist in the Video Cloud Studio Media module, you can also do using the Media Write APIs. There are a few exceptions. You cannot set or modify the following properties of videos using the Media Write APIs:

  • The viral syndication flag
  • bumpers
  • The "Force Ad Request" flag

Media API examples

We have created many Media API examples to show you different ways of using the Media API. There are also usage examples in the Media API Reference.

Related information

Now that you have an overview of the Media API, check out the other documentation about the Media API:

 

Post new comment

The content of this field is kept private and will not be shown publicly.
0

Comments