Someone emailed me a while back asking me if DKos had an API for people to access the site programatically. It had never occurred to me to have something like that before, but I can see how it would be handy. I also wrote a perl client for Voxel's hAPI for some of their services, so I had been thinking about it over the last couple of weeks again. I'm still feeling kind of sick and achy from being sick since last week, so I decided to start working on one (since hopefully I wouldn't have to think too hard), using Voxel's hAPI as inspiration. It's not anywhere near prime time yet, but I've got the basic building blocks in place. I'm implementing it here first, before I do it on DKos itself.
The endpoint is http://time.to.pullthepl.ug/api. Accessing it is easy - just make a GET or a POST request. They're called something like this:
http://time.to.pullthepl.ug/api?method=scoop.test.echo&foo=bar
This tests the "scoop.test.echo" method, which just spits whatever you give to it back. In this case, it returns this:
<?xml version="1.0" encoding="UTF-8"?>
<rsp stat="ok">
<method>test_echo</method>
<foo>bar</foo>
</rsp>
Right now, there's only two methods: "scoop.test.echo", which just echos whatever you send to it back to you, and "scoop.api_version", which returns the API version supported by the server. It's not much, but you need to start somewhere. That's also why I'm not announcing it on the site yet (since it doesn't actually do anything useful yet). Also, currently only XML is returned. I may add other ways of packaging the returned data if needed.
Eventually, the API will provide methods of doing almost anything you can do normally on the site, like view the front page, diaries, stories and comments, posting stories and comments, looking at user info, that sort of thing. There's some little things I need to figure out, like how to make authentication through the API work with Scoop's normal authentication. I'll post updates here as warranted before rolling it out on DKos.
Update: New method! Now there's also "scoop.stories.current", which lists the stories on the front page. Right now it just spits out a custom XML file, but I'm considering having it spit out RSS instead of, or in addition to, that. Currently it supports only the front page, but it's building off a method that will allow you to look at diaries, stories by a particular user, stories tagged with a particular tag, and things further in the past (like the "Next 18" link on the bottom of the stories on DKos does). This is just a shortcut method to get what's on the front page.
Updated update: "scoop.stories.list" is now active. At the moment, it takes the following arguments, all of which are called in this way: arg=option (Example URL: http://time.to.pullthepl.ug/api?method=scoop.stories.list&type=tag&tag=lighttpd):
- more - to go further back the list.
- type - what type of stories we're looking at. Can be "main", "section", "tag", and "user", with "main" being the default.
- section - what section we're looking for stories in, if type=section. "Diary" is the only meaningful option.
- tag - what tag are we looking for? Used iftype=tag.
- user - if we're getting a user's stories, specifies the user. Used only with type=user.