Developers Get your code on.


As if XML-based content syndication wasn’t enough already, we’ve got even nerdier ways to play with FeedBlendr!

  1. Link-Filling a Blend
  2. Output Options
    1. Atom
    2. RSS
    3. OPML
    4. JavaScript
    5. JSON
    6. Serialized PHP
    7. Server Side Include
  3. Customizing Output
    1. Changing The Number of Entries Shown
    2. Display Headlines Only
  4. Formatting Output
  5. Remote API
    1. Basics
    2. Creating a Blend
    3. Blend Information
    4. Retrieving Cached Blends



Link-Filling a Blend

If you just want a simple way to link someone over to FeedBlendr.com with the “template” to create a specific blend (a certain title, pre-filled URLs or an OPML file), then you can easily do that with a single link. You want to start with a base HREF of:


http://feedblendr.com/

and then you can start adding on “name/value pairs” to fill out certain details. You want to compile what’s called a querystring on the end of that link, where the querystring starts with a “?” and then each name/value pair is shown by “name=value” and is separated with a “&”.

The values you may pre-fill are:

title=
urls[]=
opml=

The urls[] element may be repeated as many times as you like to enter multiple URLs in the blend, each one is just called urls[]. So for example, to pre-fill a blend with a title of “Pre-Filled Blend” and with the URLs for the FeedBlendr Blog and for Boing Boing, you would make a link that looks like this:


http://feedblendr.com/?title=Pre-Filled%20Blend&urls[]=http%3A%2F%2Ffeedblendr.com%2Fblog%2Ffeed&urls[]=http%3A%2F%2Fwww.boingboing.net%2Fatom.xml

Note that you need to encode any URLs you use in these links properly (using something like PHP’s urlencode() function).

You could also pre-fill an OPML link in the same way, using something like this to link to a pre-filled blend with the BlogLines subscriptions of a user called “johndoe”:


http://feedblendr.com/?title=John%20Doe&opml=http%3A%2F%2Fwww.bloglines.com%2Fexport%3Fid%3Djohndoe



Output Options

There are a number of different ways to work with a blend once it’s created. Check out some of these different formats below to see what your options are, then pick what works for you.



Atom

The default (suggested) format for getting your blend is Atom. This is now a formal specification, and is more flexible and expansive than RSS. This will always contain the most amount of information possible for your blend, while other formats may lose some elements etc during translation.

To access an Atom representation of your blend, simply do a GET request against the /blends/ directory, for 9260.atom (note the .atom extension)


http://feedblendr.com/blends/9260.atom



RSS

RSS is a common format for feeds, and is required for some readers/tools. iTunes uses RSS for podcasts for example, and some extensions such as MediaRSS and GeoRSS are generally specific to RSS.

To access an RSS representation of your blend, simply do a GET request against the /blends/ directory, for <blend identifier>.rss (note the .rss extension)


http://feedblendr.com/blends/9260.rss



OPML

The OPML format output is useful as summary information, for importing the contents of a blend (as individual feeds) into another reader, and also to get some general information on a blend.

As with other formats, to access an OPML representation of your blend, simply do a GET request against the /blends/ directory, for <blend identifier>.opml (note the .opml extension)


http://feedblendr.com/blends/9260.opml

This is the same as making an API request for blend info.



JavaScript

As you’ve probably already seen, at the bottom of the information page for any blend, there’s a section where you can get the JavaScript required to drop a blend into your own website. How does this work?

Easy.

If you save the following into a file and put it on your server, you should get an extremely basic page which will demonstrate pulling a blend’s contents into your own page.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
  "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" version="-//W3C//DTD XHTML 1.1//EN" xml:lang="en">
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
  <title>My Blendr Page</title>
</head>

<body>
  <script language="javascript" type="text/javascript" src="http://feedblendr.com/blends/9260.js?l=10"></script>
</body>
</html>

The .js format supports entry limits, headlines only output and simple CSS formatting.



JSON

So you’re a hardcore JavaScript programmer and you really want to integrate the contents of a blend into your web application a little more tightly than the javascript include allows — no problem; we’ve got some JSON for you.

Using a URL very similar to the one for calling the JS include (including the querystring options), you can also get back a JSON Object, which you can then decode and use in your own application.


http://www.feedblendr.com/blends/9260.json?l=10&h=true

Calling that URL will get you a JSON object for the blend with id ‘9260’, and it’ll give you the first 10 entries in the blend, headlines only, as part of the object. You can change that number (the ’10’) to any number and you will get back up to that many entries (if there are that many available). See the section on Customizing Output for details on how to get exactly what you want.

The .json format supports entry limits and headlines only output.



Serialized PHP

If your site is coded in PHP and you’d like to be able to quickly and easily get at the important elements of your blend, then serialized PHP is for you. Using a request something like below (note the ‘9260’ and ‘.php’, which say the unique blend, and the format), you can grab a copy of your blend and access it through a native PHP array:

<?php
$blend = unserialize(file_get_contents('http://feedblendr.com/blends/9260.php?l=10'));
print_r($blend);
?>

The code above will output the array so you can see its format, which is something like this:

Array
(
    [title] => Blend Title
    [subtitle] => Blend Subtitle/Description
    [entries] => Array
        (
            [0] => Array
                (
                    [href] => http://link.to.first.entry
                    [title] => First Entry Title
                    [date] => 2007-08-16T20:40:02Z
                    [content] => <p>First entry content</p>
                     => <a href="http://www.feedblendr.com/">FeedBlendr</a>
                )

            [1] => Array
                (
	                [href] => http://link.to.second.entry
	                [title] => Second Entry Title
	                [date] => 2007-08-16T20:40:02Z
	                [content] => <p>Second entry content</p>
	                 => <a href="http://www.feedblendr.com/">FeedBlendr</a>
                )
        )
)

The .php format supports entry limits and headlines only output.



Server Side Include

If you’d rather not use JavaScript, but want an easy way to include complete output of a blend in a page, then you can also use the Server Side Include method. The output format is exactly the same as the JavaScript output, and you can use the same CSS tips for custom formatting. This uses the .ssi extension, and also supports custom output options.


http://feedblendr.com/blends/9260.ssi?l=10&h=true

The above request would get you an HTML block of headlines only for the most recent 10 entries in the blend ‘9260’. This method of direct inclusion can be used from a number of different programming languages, without any additional processing. For example, you could do the following in PHP:

<?php
echo file_get_contents('http://feedblendr.com/blends/9260.ssi?l=10&h=true');
?>

The .ssi format supports entry limits, headlines only output and simple CSS formatting.



Customizing Output

To give you more control over the output of your blend, you can use these tweaks.



Changing The Number of Entries Shown

Some of the different output formats support the addition of a ‘limit’ option, which allows you to only display a specific number of entries. To do this, simply add ‘l=10′ (that’s a lower-case L, for ‘limit’) and change 10 to however many entries you’d like to be displayed.

Remember that if this is the first option you’re adding to the URL, then precede it with a ‘?’, otherwise precede it with a ‘&’.



Display Headlines Only

If you just want to display a small news box or something, you can easily just get the headlines (rather than the content of each post as well). To do this, just add h=true (headlines-only = true) to the end of the URL.

When you output headlines only, the entry content, date and source are not displayed at all.

Remember that if this is the first option you’re adding to the URL, then precede it with a ‘?’, otherwise precede it with a ‘&’.



Formatting Output

If you’d like to make the entries that show up on your site look more like the rest of your content, no problem! CSS to the rescue.

The JavaScript and Server Side Include output formats render HTML that looks like this:

<div class="fb_output">
  <h2><span class="fb_title">Mobile Highlights</span></h2>
  <p class="fb_subtitle">This FeedBlendr feed is a blend of http://...</p>

  <div class="fb_entry">
    <h3><span class="fb_title"><a href="http://link.to.full.entry.com">Entry Title</a></span></h3>
    <div class="fb_content">Main body of the entry...</div>
    <div class="fb_source"><strong>Source:</strong><a href="http://link.to.the.source.feed">Source Feed Title</a></div>
  </div>
  <div class="fb_entry">
    <h3><span class="fb_title"><a href="http://link.to.full.entry.com">Entry Title</a></span></h3>
    <div class="fb_content">Main body of the entry...</div>
    <div class="fb_source"><strong>Source:</strong><a href="http://link.to.the.source.feed">Source Feed Title</a></div>
  </div>
</div>
<div class="fb_footer">Powered by <a href="http://www.feedville.com">Feedville.com</a>.</div>

There are a lot of CSS hooks in there that you can use to style things, changing layout, background, colors, fonts, etc. I’ll leave the details up to you.

For example, adding a rule like below to your CSS stylesheet would hide the “subtitle” information completely:

.fb_subtitle {
	display:none;
}

Note: Please do not remove the ‘Powered by Feedville.com’ message, this is a free service after all.



Remote API

I feel like FeedBlendr could probably be a pretty cool little portion of another system, so internally, it uses an API for creating blends, getting info on them and also for getting cached versions in different formats. I’m so nice that I’m releasing this API for your use – please don’t abuse it :)



Basics

The API for FeedBlendr is RESTful, which just means that it makes use of basic HTTP requests for all operations and structures those calls in a certain way, while input/output is all done as XML of some format. Where possible, it uses existing XML dialects (namely Atom and OPML), although there are some custom error messages and things like that involved.

The base endpoint for API calls is:

feedblendr.com/api/



Creating A Blend

Create a blend by POSTing an OPML document describing a list of URLs to blend to the API endpoint.

> POST /api/ HTTP/1.0

<?xml version="1.0"?>
<opml version="2.0">
  <head>
    <title>Title Of The Blend</title>
  </head>
  <body>
    <outline text="Ignored Title" xmlUrl="http://url.to.the.first.feed" />
    <outline text="Does not matter" xmlUrl="http://url.to.another.feed" />
  </body>
</opml>

You should preferably include a title element (otherwise it will be named “FeedBlendr Blend”), as well as any number of outline elements within the body. Each outline element will be treated as a separate source feed, checked, then included in the blend.

If there are any problems with the blending process, then you’ll get back an error message (encoded in simple XML) looking something like this, along with an HTTP 400 error (usually, but might depend on exactly what you do wrong):

<?xml version="1.0" encoding="utf-8"?>
<error http="400" error="1006">Invalid OPML file supplied.</error>

If there are no problems, then you’ll get something along these lines:

< HTTP/1.1 200 OK
Location: /api/123

The location referenced in the header is where you should go to get details about your new blend.



Getting Blend Information

Once you’ve created a blend, or even if it’s one that someone else created and you’re interested in using it for your own purposes, you can easily request some information about it and get back some OPML describing the contents of it.

Use the request format below, where the 9260 bit in the request is the unique identifier for the particular blend you’re interested (at the end of a /blends/ URL).

> GET /api/9260 HTTP/1.0

<?xml version="1.0" encoding="utf-8"?>
<opml version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:fv="http://www.feedville.com/developers/docs/xmlns#" fv:id="9260">
  <head>
    <title>DailyTech: Top Sources</title>
    <atom:subtitle>Keeping track of the daily technology news through key websites.</atom:subtitle>
    <atom:id>tag:feedville.com,1969-12-31:/blends/9260</atom:id>
    <dateCreated>Thu, 1 Jan 70 00:00:00Z</dateCreated>
    <dateModified>Thu, 16 Aug 07 19:01:14Z</dateModified>

    <fv:expires>Thu, 16 Aug 07 19:31:14Z</fv:expires>
    <atom:link href="http://feedblendr.com/blends/9260" type="text/html" title="DailyTech: Top Sources" rel="alternate"/>
    <atom:link href="http://feedblendr.com/blends/9260.atom" type="application/atom+xml" title="Atom 1.0" rel="alternate"/>
    <atom:link href="http://feedblendr.com/blends/9260.rss" type="application/rss+xml" title="RSS 2.0" rel="alternate"/>
  </head>
  <body>
    <outline type="rss" text="Digg / Technology" xmlUrl="http://digg.com/rss/containertechnology.xml" fv:id="39258"/>
    <outline type="rss" text="Techmeme" xmlUrl="http://www.techmeme.com/index.xml" fv:id="37356"/>
    <outline type="rss" text="GigaOM" xmlUrl="http://gigaom.com/feed/" fv:id="1981"/>
    <outline type="rss" text="Engadget" xmlUrl="http://www.engadget.com/rss.xml" fv:id="858"/>
  </body>
</opml>

Note a few interesting things in there:

  1. The opml@fv:id attribute is the internal identifier of this blend (should be the same as what you used to request this info)
  2. The opml/head/title element is the title provided by the user for this blend
  3. Each opml/head/atom:link element points to a different format of this blend
  4. The feeds within the blend are shown as outline elements within the body
  5. Each feed listed will have a fv:id attribute also, which is that feed’s specific identifier within the Feedville system

As usual, if there is some sort of error, you’ll get back an XML-encoded error message telling you what the problem is.



Retrieving A Cached Copy of A Blend

Getting a cached copy of a blend is the same as requesting the blend as if you were putting it in your news reader. All you need to know is the unique identifier for a particular blend, and what format you’d like to retrieve it in. Then you can do something like this:

> GET /blends/9260.atom HTTP/1.0

and get back an Atom version of blend number 9260. Easy. The different formats (replace .atom with these) supported are available in the Output Options section.