The Brightcove Media API is a REST-based API for accessing the content and metadata in your Brightcove account. Because it is a REST-based API, it can be accessed from a wider 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, access to the API is protected with tokens that you pass as a parameter when making API calls. Like other web-based APIs, tokens are generated for you by Brightcove and protected by you.
The first thing you need to do to get started is to get the tokens for your account.
Then, after you read this introduction, check out the other documentation about 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 methods and write methods.
find_all_videos, which returns a list of VideoDTOs, where each VideoDTO contains the metadata for a specific video. 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.create_video, which you can use to pass in a video file, together with its associated metadata, and create a video in your Brightcove account.Method calls using REST are basically HTTP GET requests(for read methods) or POST requests (for write methods) to a particular URL on Brightcove's 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 Brightcove Services through IP addresses is not supported and should be avoided at all times. Brightcove IP addresses can change at any time without notice; a change can cause any systems trying to access them via IP address to fail.
Method calls also require a token. Tokens are issued to accounts by Brightcove and give you access to your account using 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, token=<tokenString>, where tokenString is your URL-encoded token.
Note: 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. For more information about tokens, see Managing Media API Tokens.
For example, to retrieve all videos in your account, 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 unformated. 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 token.)
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, includes facilities for make HTTP requests. These are what you use to include API calls in your application. In addition, Brightcove-savvy developers have created SDKs that you can include in your applications as native classes for easy API access. For example:
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, you'll want to wrap the HTTP request in a function and call it in response to some programmatic event, like an onClick event. You'll also need to 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; 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 Brightcove 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 Brightcove. Another possible architecture could be one with a Flash client, using Flash's HTTP stack. You could possibly use AIR, Adobe's new desktop client, to create a Flash-based desktop uploader application.
The basic Read API calls, like find_all_videos, can be refined with additional parameters. The API reference lists the complete set, but here are just a few of the things you can do:
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.
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.
To enhance performance, API calls are cached on Brightcove servers. When a call is made, the cache is checked first. If that call hasn't been cached or the cache has expired, the call goes straight to the database and the results are sent back and also cached. The cache will expire after 5 minutes. If you make additional calls within that window the results will come from the cache rather than the database.
Caching currently doesn't take into account changes you may make to your library using the Brightcove 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 developing; the API may be working correctly, even if you're not seeing the correct results.
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:
If your output is MRSS, errors are included in an <error> element that includes an error code and message.
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'll be informed of what might have gone wrong and can act on it appropriately.
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.
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.
We have created many examples to show you different ways of using the Media API and plan to add more.