CommonBits: Build your own News site with our XML REST APIs for CommonTimes.org

We've released an early set of XML REST APIs for CommonTimes.org, a social bookmarking community for news readers. If we get requests for CommonBits or CommonTunes APIs we can add those pretty easily.

The CommonTimes.org APIs allow you to remix the news - essentially, you could build your own news Web site with any design. We are especially interested in designers and coders who want to remix the design of our front page news site and user channels. Be sure to let us know about the cool stuff you create.

These APIs may change and evolve - this is an early draft of how to use them. I'd appreciate your feedback as well. Post your comments below or email me. A general overview of the uses of XML REST APIs is here.

Keep in mind this section is for programmers only. You'll need some development skills to parse the XML files that our site uses to answer your queries.

Obtaining your API Authorization Key
In order to use the APIs, you'll need an authorization key from our Web site. Visit CommonTimes.org, login or register and then visit this page. The key will be in this form 451-jruUsdwLDNMao. Copy this information into your code as described below.

Draft API Definitions
To retrieve XML data from CommonTimes, you query a specific Web page applying arguments for the function calls in the path. e.g. http://api.commonmedia.org/auth_key/site_id/method/arg1/arg2/argn

This will return the data as basic XML. To add an XSL stylesheet transformation, add the argument ?xsl=<stylesheet_url> e.g.
http://api.commonmedia.org/auth_key/site_id/method/arg1/arg2/argn?xsl=http://www.yoursite.org/yourstyle.xsl

To see an example of our initial incomplete front page remix, try this:
http://api.commonmedia.org/<your-authkey>/times/frontpage?xsl=http://api.commonmedia.org/style.xsl

auth_key is the string you copy from the page above e.g. 451-jruUsdwLDNMao

site_id specifies which CommonMedia site you are calling e.g. times is CommonTimes.org. There are no other sites enabled for the API at this time.

method refers to the function you are requesting e.g. frontpage returns an xml file with the information for all the sections and stories on the front news page.

Each method has its own set of arguments. The methods and arguments are defined below.

Method List

frontpage - returns all the sections and stories from the CommonTimes front news page. This is the method you should use if you want to remix your own front news page.

e.g. http://api.commonmedia.org/<your-authkey>/times/frontpage

popular - returns a list of the most widely shared stories on the CommonTimes site.
arg1 = number of rows

e.g. http://api.commonmedia.org/<your-authkey>/times/popular/7

getsection - returns the stories most widely shared in a specific news section.
arg1 = section name
arg2 = number of rows

e.g. http://api.commonmedia.org/<your-authkey>/times/getsection/u.s.-news/7

gettag - returns the stories most widely shared for a specific topic
arg1 = tag or topic name
arg2 = number of rows

e.g. http://api.commonmedia.org/<your-authkey>/times/gettag/karl-rove/7

getchannel - returns a list of stories from a given member's channel.
arg1 = member name
arg2 = number of rows

e.g. http://api.commonmedia.org/<your-authkey>/times/getchannel/jeff/7

getcommunity - returns a list of stories most widely shared by a specific community.
arg1 = community name
arg2 = number of rows

e.g. http://api.commonmedia.org/<your-authkey>/times/getcommunity/Slashdot%20Readers/7

Story XML Overview

Here is some example XML returned for each story:

<story>
<rank>1</rank>
<channels>3</channels>
<id>2935</id>
<title>Bill Gates' Gets Schooled by Bob Geballe</title>
-
<link>
http://www.seattleweekly.com/features/0529/050720_news_gateseducation.php
</link>
<comments/>
<date>Tue, 19 Jul 2005 21:04:07 +01:00</date>
<source>Seattle Weekly (tbd)</source>
<thumbnail/>
<image/>
<postedby/>
<slug>billgatesgetsschoole</slug>
</story>

The rank is essentially an ordering index for each XML result list. Channels is a count of the number of readers who have bookmarked this story. Id is the code for our database for this story which can be used for coding command links to add the story to a user's channel. Slug is the keyword which can be used to create links to commands for emailing friends, posting comments et al. If you view the source of the home page of CommonTimes.org, you'll see how these links are constructed.

For example:

email a friend - http://www.commontimes.org/<slug>#tellfriend
post a comment - http://www.commontimes.org/<slug>#comments
add to channel - http://www.commontimes.org/submit_times.php?contentid=<id>

In Conclusion
There are threshold limits built into the system right now to prevent abuse and overloading. Let me know if you run into them legitimately and need them changed.

If you have any questions, comments or feedback on our APIs and XML structure, please email me. If you come up with a great remix or idea, please let me know.

Thanks for your support.