API Changes

[Jeff Hodsdon]

Hey all,

We're looking to change the way Digg data is accessed and contributed via the API in a new version.  Our goals are to have a RESTful[1] and easy to understand API that gives power to the developers to create cool new applications.  In forth coming versions of the API, people will be able to not only read data, but also contribute data too.  As we thought about how to organize these new methods, we found the currently more RESTful URL structure we have may propose some issues.

There are two ideas that we have tossing around and we would like to get feedback from the community, or gather other ideas.  The ideas are as follows:

Keep the existing self descriptive url path structure for endpoints for contributing data (RESTful).  This would mean, for digging, something like this:

/story/{id}/digg

which is very similar to getting diggs for a story:

/story/{id}/diggs

A change we are thinking about is more of a method based API with a single URL and arguments (REST-like).

/endpoint?method=digg.get&story_id=123
/endpoint?method=digg.new&story_id=123

This method is similar to Flickr's API[3] and Facebook's[4].  The first method, which we currently use, is similar to Twitter's[5].

What do you guys think?

-Jeff

[1] - http://en.wikipedia.org/wiki/Representational_State_Transfer
[2] - http://en.wikipedia.org/wiki/KISS_principle

[3] - http://www.flickr.com/services/api/

[4] - http://wiki.developers.facebook.com/index.php/API

[5] - http://apiwiki.twitter.com/Twitter-API-Documentation

[goodtest]

I have written apps for both twitter and facebook. I think its a close
call, I prefer facebook style with single-url, different params
because it feels like its more flexible than RESTful.
More importantly, I am *very* excited to see that soon we can 'digg'
from our own app. We can integrate with our social apps and it would
be excellent. Whats the expected date btw?

[Bill Shupp]

On Jul 27, 2009, at 5:22 PM, goodtest wrote:

>
> I have written apps for both twitter and facebook. I think its a close
> call, I prefer facebook style with single-url, different params
> because it feels like its more flexible than RESTful.
> More importantly, I am *very* excited to see that soon we can 'digg'
> from our own app. We can integrate with our social apps and it would
> be excellent. Whats the expected date btw?

Thanks for the feedback. There is no official date set right now, but
we hope to have it out soon. We'll certainly post more details when
they are official.

Cheers,

Bill

[Scott]

Personally I think it's just a matter of apples versus bananas.
Neither seems inherently 'better' than the other; just different (and
there may be something to be said for being similar to the other
players; facebook and twitter).

I would prefer if it just stayed the same since I would prefer to not
have to rework my existing apps and risk them all failing all of a
sudden.

And if you want to be neurotic about it... the existing structure
uses shorter calls... less data transfer for cellphones!

I kid. Seriously though, just keep it the same. :)

Scott Fitzhugh
Shovel

[samfind Bookmarks Bar]

Jeff,

From the article I read (on Digg) from VentureBeat - it sounds like
you are trying to make it easier for more stories to be dugg. That is
important to keep your information timely. So, great!

I think an important factor for Digg should be ease of developers to
use your API. If you look at twitter, they have made it very easy for
developers to make applications because they have a very easy to
follow API that gives you extensive control over twitter. This has
allowed lots of developers to easily make creative apps, giving lots
of people different options of how to tweet. Giving twitter lots more
tweets. I think the same goes for Digg. What ever you choose - make
it super simple for developers to meaningfully integrate no matter
what type of app they are building.

For our particular app stands outside of the website on the browser as
a Firefox add-on. When the user clicks our Digg button, it takes the
story's URL as it is presented on the browser and submits it to Digg.
Currently it takes the user to the Digg website. But with your new
API, it would submit it directly and bump up the vote. Cool. By using
your existing system, I have noticed that some websites have a
different URL in their page based Digg button than the actual URL of
the webpage, maybe they add something like "&source=digg" to the URL
of the Digg button. This makes it so the URL that we are submitting
to, the page's actual URL does not sync up with the Digg button URL
causing sync issues on your end requiring users to go through the
hassle of determining if their story is unique.

All of this is to say, if, when a user clicks the button to Digg, you
can more accurately (than you currently do) determine whether a Digg
is from a unique page, either by:
- scanning the text of the page to check if a digg button exists on
the page or
- scanning the content of the page to see if it is unique despite the
URL being slightly different,
that would be helpful to users, so they don't have to manually check
if their submission is unique and helpful to developers so our buttons
do not send the users to digg different URLs than the page is sending
users to Digg.

Just a few thoughts,

Sam Deskin