The Video Curation, Publishing, & Monetization Platform

Developer Center

Developer's Guide

Overview

The Magnify API provides REST style access to the major components of any Magnify video channel. Once you have issued yourself an API key (see below), you can access all API functions by making an HTTP GET request to a URL in the following format:

http://(channel).magnify.net/api/(resource group)/(resource)[?parameter=...&parameter=...]

The channel is the same one you normally use to access your Magnify site. The resource group identifies the type of data you would like to retrieve, currently:

content (predominantly video)
list (playlists)
user
activity (comments, ratings, tags, etc)

Each resource group in turn contains several resources that specify exactly what you'd like to do. For example, resources for user:

show
find

show will display the details for a particular user, and find will return a list of users matching a particular search string. To specify what we're searching for, we should provide a parameter:

?vq="John Smith"

The complete URI to search for users named "John Smith" on some channel will then look like this:

http://somechannel.magnify.net/api/user/find?vq="John Smith"

The API response to a request is an XML document formatted in the Atom standard. We examine one below.

Anatomy of a Request and Response

Let's take a look at a more complex request, using most of the parameters available in the API:

http://somechannel.magnify.net/api/content/find?vq=colbert&per_page=5&

page=2&sort=popularity&key=SD2N2BH4J6KS216R

Let's break it down:

http://somechannel.magnify.net/api/ - the base URI for API access to the 'example' channel
content - the resource group, which indicates the type of thing that you are dealing with
find - the resource within that group, i.e. the action to be performed
vq - the string that we are searching for, in this case "colbert"
per_page, page - the number of items to return per page, and the page number
sort - the sorting order
key - the API key used to identify yoruself to the application

A response to this request will be an Atom <feed> containing an <entry> element for each returned video, plus additional metadata:

<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns="http://www.w3.org/2005/Atom"
      xmlns:magnify="http://www.magnify.net/api/magnify"
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
      xmlns:media="http://search.yahoo.com/mrss/">
  <generator version="beta"
             uri="http://www.magnify.net/api/">Magnify.net API</generator>
  <updated>2008-09-02T19:40:16Z</updated>
  <id>http://somechannel.magnify.net/api/content/find?vq=colbert&amp;per_page=5&amp;page=2&amp;sort=popularity</id>
  <link rel="self"
        href="http://somechannel.magnify.net/api/content/find?vq=colbert&amp;per_page=5&amp;page=2&amp;sort=popularity"
        type="application/atom+xml" />
  <link rel="next"
        href="http://somechannel.magnify.net/api/content/find?vq=colbert&amp;per_page=5&amp;page=2&amp;sort=popularity&amp;start=11"
        type="application/atom+xml" />
  <link rel="previous"
        href="http://somechannel.magnify.net/api/content/find?vq=colbert&amp;per_page=5&amp;page=2&amp;sort=popularity&amp;start=1"
        type="application/atom+xml" />
  <title>Search for Videos at example: colbert</title>
  <rights>Copyright 2008, Magnify Networks</rights>
  <opensearch:Query searchTerms="colbert"
                    role="request" />
  <opensearch:startIndex>6</opensearch:startIndex>
  <opensearch:itemsPerPage>5</opensearch:itemsPerPage>
  <opensearch:totalResults>22</opensearch:totalResults>
  <entry>
    <link rel="self"
          href="http://somechannel.magnify.net/api/content/show?id=Y0K19F52G6XG9ZFQ" />
    <link rel="alternate"
          href="http://somechannel.magnify.net/video/Stephen-Colbert-Princeton-200" />
    <author>
      <name>Anonymous</name>
    </author>
    <magnify:id>Y0K19F52G6XG9ZFQ</magnify:id>
    <updated>2008-07-30T23:16:28Z</updated>
    <title>Stephen Colbert - Princeton 2008 - Bush Comment</title>
    <id>http://somechannel.magnify.net/api/content/show?id=Y0K19F52G6XG9ZFQ</id>
    <content>mob biblicone wrote: Stephen Colbert comments about the class of 2008 being the last class to graduate under the presidency of George W. Bush.</content>
    <media:thumbnail url="http://thumbnails.truveo.com/0001/21/FE/21FEDCAE09E8237E4B05A7.jpg" />
    <media:content width="300"
                   medium="video"
                   url="http://somechannel.magnify.net/embed/content/Y0K19F52G6XG9ZFQ/00FF00/w300"
                   type="text/html"
                   height="360" />
  </entry>
    ... (4 more entries) ...
</feed>

In this case, this feed provides 5 items starting with number 6 (that is, the second page) of 22 results for the search term "colbert". See the feed page for more information on the feed format, and individual function reference pages for the entry elements.

A Word on Standards

We've tried to to make the result feeds generated by our API as standard-compliant as possible for maximum clarity and compatibility with your existing tools and services. That means using standard Atom elements and widely used extensions whenever it's possible without straining or subverting their meaning. We're pleased to report that all content and list resources return Atom-compliant feeds.

In some cases, standard Atom elements are a poor fit for the information we're trying to represent, such as with Magnify user profiles. For these, we've defined our own namespace at http://www.magnify.net/developers/api/ns which is used for results from e.g. user/show.

Embedding Video

Magnify content is served inside lightweight iframes. Instead of serving a bulky inline <object>/<embed> tag in our feeds, we provide only what you need: the iframe url and geometry inside the <media:content> element.

To place it on your page, just pass the values to an <iframe> tag. For example, this content element:

<media:content medium="video" url="http://somechannel.magnify.net/embed/content/HMKCP3TLVC8KW19N/" type="text/html"/>

could be displayed with the following iframe tag:

The served player will automagically scale to the dimensions of your iframe. To avoid excessively straining the magic, keep the iframe width between 300 and 600 pixels, and the height approximately 1.2 times the width. The PHP client library will pick this aspect ratio by default.

Authentication and API Keys

Magnify uses API keys to identify your application and determine what data it should have access to.

You can create, revoke and manage API keys on the API Management page in your Site Admin Area. Simply click "Create New Key" to have a fresh key generated for you and associated with your channel.

Only one key needs to be used for any particular application, but you can create up to 5 keys if you have several developers working on independent applications interacting with your channel.

A key should be provided with all requests to the API to make sure your channel only interacts with the applications that you want it to. You can do this in one of two ways:

As a query string parameter in the form &key=123456789ABCDEF0, for example
http://somechannel.magnify.net/api/content/find?vq=Bob&key=SD2AP414J6MY216R
As a value for the X-Magnify-Key header in your HTTP request, for example
X-Magnify-Key: SD2AP414J6MY216R

We recommend using the X-Magnify-Key header field for all requests to avoid having your key logged by intermediate caching or proxy servers.

If you don't provide a key, or provide an invalid one, you will receive a 401 Unauthorized/Invalid API Key error.