XML-RPC.ComUserLand
    Simple cross-platform distributed computing, based on the standards of the Internet.



Spec

Mail List

Directory

C/C++

RSS

OPML

XML

Dave



XML-RPC interface for the NewsRiver aggregator

By Jake Savin and Dave Winer, Nov 7, 2002; Updated Jan 11, 2006.

Background 

For an overview, see Scripting News for 1/11/06.

The goal is to create an XML-RPC interface for aggregators, with a first implementation for the NewsRiver aggregator that's an add-on for the OPML Editor.

This document explains the concepts and entry-points of the API.

username and password  

All methods take as their last two parameters username and password. (Prior art for this is the Blogger API and the MetaWeblog API, which with one exception takes username and password as the last two parameters.)

In Radio UserLand, these correspond to the remote access username and password. In the OPML Editor and Frontier, a new sub-table is created at aggregatorData.prefs.security, which contains username and password, and a boolean, flRpcInterfaceEnabled which enables the aggregator's XML-RPC interface. The interface is disabled by default. In the OPML Editor there's a preferences panel in newsRiver.root that lets the user change the settings.

aggregator.subscribe (url, username, password) returns struct  

Subscribes to an RSS feed, and returns a struct with the following elements: title, link and description from the RSS feed, url, which is the url of the feed, language and image (only if present in the feed). image is a struct, containing url, title, height and width.

aggregator.unsubscribe (url, username, password) returns boolean  

Removes a subscription, and returns true.

aggregator.getSubInfo (url, username, password) returns struct  

Gets information about a subscription, and returns a struct, which is identical to the struct returned by aggregator.subscribe.

aggregator.getSubs (username, password) returns struct  

Gets all subscriptions, and returns a struct, which contains a struct for each subscription whose name is the URL of the RSS feed. The structs are identical to the structs returned by aggregator.getSubscriptionInfo and aggregator.subscribe.

aggregator.getLastScanInfo (username, password) returns struct  

Returns a struct with the following elements: ctNewItems which is the number of new items read in the last scan, flScanRunningNow, a boolean which is true when a scan is in progress, and whenComplete which is the date/time the last scan was completed.

aggregator.getRecentItems (numberOfItems, username, password) returns struct  

Returns a struct of up to numberOfItems structs, whose name is the item's itemId which is a string identifying the item. Each struct has the following elements: itemText from the RSS item's description, channelTitle and channelLink from the RSS feed containing the item, url which is the url of the RSS feed, when which is the date/time that the item was read by the aggregator, and itemId.

The struct also contains the following elements, only if present in the item: title, link, pubDate, and author from the item, sourceTitle and sourceUrl from the source sub-element of item, categories, which is an array of strings, permalink, which is the url specified by guid with an isPermaLink="true" attribute, comments, which is the url of the comments page for the item, and enclosure. enclosure is a struct, containing url, bytes, mimeType and filePath (only if the enclosure has been downloaded).

aggregator.getItemsSince (when, username, password) returns struct  

Returns a struct of structs for all items aggregated since the date/time specified by when. The structs are identical to the structs returned by aggregator.getRecentItems.

aggregator.getRecentItemsForSub (url, numberOfItems, username, password) returns struct  

Gets the most recent items from a subscription, and returns a struct of up to numberOfItems structs, which are identical to the structs returned by aggregator.getRecentItems.

aggregator.getItemsForSubSince (url, when, username, password) returns struct  

Returns a struct of structs for all items from a subscription, which were aggregated since the date/time specified by when. The structs are identical to the structs returned by aggregator.getRecentItems.

aggregator.getItem (itemId, username, password) returns struct  

Gets the item specified by itemId, and returns a struct, which is identical to the structs returned by aggregator.getRecentItems.

aggregator.deleteItem (itemId, username, password) returns boolean  

Deletes the specified item, and returns true.

aggregator.deleteItems (itemIdArray, username, password) returns boolean  

Deletes items whose IDs are specified in itemIdArray, and returns true.

Change notes  

11/14/02; 3:06:26 PM by JES -- Added two new methods: aggregator.getItemsSince and aggregator.getItemsForSubSince, which get items aggregated since the specified date/time. Added the following elements to the struct representing an item, only if present in the item: title, link, pubDate, author, categories, sourceTitle, sourceUrl, permalink and enclosure.

11/11/02; 1:16:48 PM by JES -- Added two new elements to the struct representing an item: channelLink from the RSS feed, and comments, which is the url of the comments page for the item (only if present).

11/8/02; 6:26:02 PM by JES -- Added a new entry-point, aggregator.getLastScanInfo, which returns information about the last scan. Changed the return type of aggregator.getSubs, aggregator.getRecentItems and aggregator.getRecentItemsForSub from array of structs to struct. This is consistent with the MetaWeblog API's metaWeblog.getCategories, xmlStorageSystem.getMyDirectory and various entry points in Manila's RPC Interface.

© Copyright 2004-2011 Scripting News, Inc.
© Copyright 1998-2004 UserLand Software, Inc.
XML-RPC is a trademark of UserLand Software, Inc.
Posted: 1/11/06; 11:38:02 AM Pacific.

Create your own Manila site in minutes. Everyone's doing it!