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:
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:
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
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:
The complete URI to search for users named "John Smith" on some channel will then look like this:
The API response to a request is an XML document formatted in the Atom standard. We examine one below.
Let's take a look at a more complex request, using most of the parameters available in the API:
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"
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&per_page=5&page=2&sort=popularity</id> <link rel="self" href="http://somechannel.magnify.net/api/content/find?vq=colbert&per_page=5&page=2&sort=popularity" type="application/atom+xml" /> <link rel="next" href="http://somechannel.magnify.net/api/content/find?vq=colbert&per_page=5&page=2&sort=popularity&start=11" type="application/atom+xml" /> <link rel="previous" href="http://somechannel.magnify.net/api/content/find?vq=colbert&per_page=5&page=2&sort=popularity&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.
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.
Magnify content is served inside lightweight iframes. Instead of serving a bulky inline
<embed> tag in our feeds, we provide only what you need: the iframe url and geometry inside the
To place it on your page, just pass the values to an
<iframe> tag. For example, this content element:
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.
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:
&key=123456789ABCDEF0, for example
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.
Reference information for all API functionality is available on the Feed, Content, User and other pages corresponding to resource groups. More usage examples, code snippets in several languages and a PHP client library can be found in the Sample Code section.