digg API.NET - C# Implementation of digg Web Services

Download DiggAPI.zip - 30.6 KB

example implementation

Table of Contents

Introduction
Background
The Digg API
The Base Url
The Application Key
Parameters
Endpoints
The C# digg Interface
StoryCollection Object
Story Object
Code Examples
Setting Library Properties
Get Most Popular Stories
Get Upcoming Stories
Get Stories By Topic
Get Upcoming Stories By topic
Get Stories Submitted By a User
Get Stories a User Has Digged
Get Story By it's ID
Get Comment For a Story
Get Valid Topics
Conclusion
ToDo
History

Introduction

Digg.com is the popular social news web-site that allows it's community to dictate which articles make it to the site's front page and which end up in the pits of internet hell, never to be read... by anyone. The concept is simple, digg.com members search the web for articles that they find interesting and then submit them to the site. The users of the site vote (or digg) on the articles and if enough people vote on the article it will be promoted to the front page. In addition, each article maintains a comment page where digg users can comment (or flame one another endlessly) on topics relating to the article.

Aside from being entertaining, digg.com provides a wealth of priceless information regarding comtemporary culture, science, sports, business, lifestyle, and technology. In the past, aggregating this data meant one had to use screen-scraping techniques with a mountain of Regular Expressions. Thankfully, digg has now provided users with a rich API for getting at it's data. My goal was to abstract the interface into a .NET object oriented library that can be imported into any project. It's still lacking a few features I'd like to add but it's certainly useable.

Background

Quite some time ago I rolled my own personal Rss Aggregator and viewer and at that time I discovered a great open-source component for parsing Rss feeds, Rss.NET. The library had worked flawlessly up until a few months ago when I began to notice that the feeds from digg.com were timing out. The Rss.NET library worked with all my other feeds but for some reason started to receive 403 Forbidden messages while trying to establish the HttpWebRequest to the digg.com servers. At this time I began researching the digg API for an alternate method for obtaining the feeds. While building a .NET library to interface with the digg API I discovered that the Rss.NET library was failing due to not setting all the required properties for the WebRequest object such as UserAgent, Credentials, and Accept. I have since added the necessary properties and sent a copy of the change to the Rss.NET developers.

However, since I had already come this far with the digg API I set about completely the portions I had begun and this article outlines that effort.

The Digg API

The full documentation is available from the digg.com api site.

The Base URL

The base url for accessing the api is http://services.digg.com/. However, if you attempt to access that url on it's own you will receive a (403) Forbidden error due to the fact that you have not provided an appkey value. The appkey is probably going to end up being a unique key that must be purchased once digg sells out, but for the moment, it's any valid url.

Application Key

The application key or appkey value represents the requestor of the data. It can be any valid Url and presently is only used to track which web service users are consuming what data. The appkey value is appended at the end of the query string. All queries must provide an appkey value in order to receive the data.

http://services.digg.com/story/popular?appkey=http://www.codeproject.com

Parameters

The digg.com API documentation contains all the parameters for each request but the most common ones are:

• count - the amount of records to return (0-99)
• sort - promote_date-desc, promote_date-asc, submit_date-desc, submit_date-asc

http://services.digg.com/stories/popular?count=25&appkey=http://www.codeproject.com 

Endpoints

Endpoints represent the url location to post your query. Below you'll see most of the endpoints available.

/stories - All stories. 
/stories/popular - Popular stories. 
/stories/upcoming - Upcoming stories. 
/stories/container/{container name} - All stories from a given container.
/stories/container/{container name}/popular Popular stories from a given container.
/stories/container/{container name}/upcoming - All stories from a given topic.
/stories/topic/{topic name}/popular - Most Popular stories in a topic
/stories/topic/{topic name}/upcoming - Upcoming stories from a given topic.
/story/{story id} - Identified story.
/stories/{comma-separated list of story ids} - A list of stories with the given ids.
/user/{user name}/submissions - Stories submitted by given user.
/topics - Get a list of all topics. 
/users - All users. 
/user/{user name} - Named user.
/user/{user name}/friends - Named user's friends.
/user/{user name}/activity - All digg and comment activity for a given user.
/user/{user name}/activity/diggs - All digg activity for a given user. 
/user/{user name}/activity/comments - All comment activity for a given user. 
/story/{story id}/activity - All digg and comment activity for a given story. 
/story/{story id}/activity/diggs - All digg activity for a given story.. 
/story/{story id}/activity/comments - All comment activity for a given story. 

The C# digg Interface

StoryCollection Object

The StoryCollection is the heart of the library. When the StoryCollection object is instantiated, it creates a Story object to hold all the values of each story. So you just need to enumerate the story object contained in the collection to access the values. In order to construct the object you must send in the:

• ArticleType - enumeration for the query to run (see below)
• ArticleTypeCriteria - optional: the search criteria for certain queries

//In the references add
using Baileysoft.Rss.DiggAPI;



StoryCollection articles = StoryCollection(ArticleType.byUserDiggs, "thund3rstruck");

   foreach (Story article in articles)
        Console.WriteLine(article.Description);

Story Object

The Story type is an object representation of each article. You enumerate the StoryCollection and extract any values you need from the Story objects. See the properties below.

Code Examples

NOTE: All code examples require a reference in the project to the DiggAPI.dll and declarations

using Baileysoft.Rss.DiggAPI

Setting Library Properties

You can pre-define global settings by changing the field values in Globals.cs or you can define them programmatically (e.g. see below)

  Globals.Count = "3"; //max 99
  Globals.AppKey = "http://www.codeproject.com"; //the referring site (your site)

Get Most Popular Stories

 Globals.Count = "25";
 Globals.AppKey = "http://www.codeproject.com"; 

 StoryCollection articles = new StoryCollection(ArticleType.popular);
 foreach (Story article in articles)
       Console.WriteLine(article.Title);

Get Upcoming Stories

 Globals.Count = "25";
 Globals.AppKey = "http://www.codeproject.com"; 

StoryCollection articles = new StoryCollection(ArticleType.upcoming);
foreach (Story article in articles)
     Console.WriteLine(article.Title);

Get Stories By Topic

 Globals.Count = "25";
 Globals.AppKey = "http://www.codeproject.com"; 

 StoryCollection articles = new StoryCollection(ArticleType.topic, "apple"); //must be a valid topic
 foreach (Story article in articles)
      Console.WriteLine(article.Title);

Get Upcoming Stories By topic

 Globals.Count = "25";
 Globals.AppKey = "http://www.codeproject.com"; 

 StoryCollection articles = new StoryCollection(ArticleType.topicUpcoming, "apple"); //must be a valid topic
 foreach (Story article in articles)
      Console.WriteLine(article.Title);

Get Stories Submitted By a User

 Globals.Count = "25";
 Globals.AppKey = "http://www.codeproject.com"; 

 StoryCollection articles = new StoryCollection(ArticleType.byUserSubmissions, "thund3rstruck");
 foreach (Story article in articles)
       Console.WriteLine(article.Title);

Get Stories a User Has Digged

 Globals.Count = "25";
 Globals.AppKey = "http://www.codeproject.com"; 

 StoryCollection articles = new StoryCollection(ArticleType.byUserDiggs, "thund3rstruck");
 foreach (Story article in articles)
        Console.WriteLine(article.Title);

Get Story By it's ID

 Globals.Count = "25";
 Globals.AppKey = "http://www.codeproject.com"; 

 StoryCollection articles = new StoryCollection(ArticleType.byId, "2572048");
 foreach (Story article in articles)
        Console.WriteLine(article.Title);

Get Comments for a Story

 
Globals.Count = "25";
Globals.AppKey = "http://www.codeproject.com"; 

StoryCollection articles = new StoryCollection(ArticleType.byId, "3678318");
foreach (Story article in articles)
{
    foreach (Comment comment in article.Comments)
    Console.WriteLine("{0}: {1}", comment.User, comment.Text);
}

Get Valid Topics

 Globals.AppKey = "http://www.codeproject.com"; 

 TopicsCollection topics = new TopicsCollection();
 foreach (string topic in topics)
        Console.WriteLine(topic);

Conclusion

This library came entirely out of me not taking the time to dive into RSS.NET to identify why digg feeds timed out with (403) errors. In any event, this was a neat project and if it gets a good reception I may keep working on it.

ToDo:

• Classes for submitting articles
• Classes for digging articles

History

I have not updated the documentation in this article yet but there are a few new comment handling types for enumerating article comments. See the download for additional examples.

• 07/24/2007 - Submitted article for DiggAPI v.01
• 10/05/2007 - Added methods for enumerating comments