In the server mess I had to take the FeedHose server off the air so I could reorganize things. Now I'm ready to turn it on again.
The main entrypoint is the default page. It's meant to be called from an application. It's a long-poll, meaning it returns when something new is available from the indicated hose, or if it times out. In either case you're expected to loop back around and call it again.
Here's an example call that times out after three seconds, returns JSON-formatted news from Hacker News. (If no new stories came in during the three seconds, which is almost a certainty, you'll just get metadata.)
4. seed, a string returned from a previous call to the hose, passed back to the next call. If any new items came in while you were processing the the previous call, or if your client rebooted or otherwise went away for a long time, passing back the seed assures that you don't miss any news. If you don't mind possibly missing some news you don't have to specify the seed.
The values returned are straight from RSS 2.0. elements like title, link, description, pubDate, etc. There are three additional values that are passed back, the feedUrl, feedTitle and feedLink of the feed the item came from. Hoses can be made up of many feeds, and it's sometimes useful to know which feed an item came from.
1. recent, which just returns the latest stories. It's useful to see what you get back from the feednose while you're developing, or to show someone roughly what the hose looks like at a technical level. It looks for several optional parameters, as described above: name and format that determine which hose is queried and what format the returned text is in. There's an additional optional parameter, count. If not specified it's 3. The maximum count is 15.
2. seed, which returns the current seed without waiting and without returning any news. You can specify the name and format, as optional parameters, as described above.