For any API, simplicity and documentation (lots of usage examples!) are probably the top considerations. But it's interesting to think about what's special to news. A few thoughts:

• If you're hoping people will visualize or analyze your data, make bulk downloads easy. In addition to a "query" interface, you could make available a big zip file of all your data.
• You might have a lot of non-traditional developers, so documentation is even more important than usual.
• People may already be scraping your site for data. If you can find traces of automated activity in your logs, you'll have a head start in figuring out what people want--and could save some load on your servers.
• In a news context, copyright matters. Have a clear license--any uncertainty could make people shy away.
• Look for good "role model" APIs: find other media-related sites that have APIs that are used in interesting ways.

Martin Wattenberg

80

Make it RESTful!

1. The technical, Wikipedia explanation
2. The conversational explanation

Web frameworkwise, were you to use Django, the leading tool is Piston.

As my Ruby on Rails ignorance is vast, all I have to offer is this.

(After further Googling, If you prefer Ruby (without the "on Rails"), there's a whole separate Ruby framework you might want to look at, Sinatra.)

John Heasly

472

To me, the first characteristic of a great news platform API is great content. If you find yourself saying, "I wish that we had an API for X", then it might reason that others have the same need (or would see it if the API was built). But going with what you know is a good start: articles, photos, comments, newsroom data. If you haven't worked with APIs much, build something that you will use yourself. That will make you much more aware of how design decisions can impact the spread and usefulness of an API. I learned this many times over doing our Congress API.

Derek Willis

305

Assuming the API you're referring to is a read API (ie, it will be used to consume data from your app rather than input data into it), having an RSS/Atom feed is already a decent start.

If you're using a mature CMS, RSS is most likely already built in. If you're rolling your own, you probably want to add it as early as you can. It's not too hard, and most languages have libraries to make it simpler.

Ideally you'd want to make sure that the feed contains the entire story (ie, not only a summary version) and provide feeds for any data you'd expect the API users to consume (comments, search results, etc). Also, one of the often overlooked benefits of RSS is auto discovery - which, among other things, allows browsers to display the RSS icon by the address bar, for example in this page - using it correctly lets developers easily map content URLs to their relevant API ones.

niryariv

0

The Guardian has been a big proponent of news APIs, and seems to have found several ways to make their news content and data sets useful. I'd be careful about giving the cow away, so to speak, in terms of allowing downloads of your data, but that's something that's probably unavoidable.

I think some good uses would be:

• APIs that let you access, sort, trim, and filter large data sets, which might be the most easy, natural fit.
• Breaking news content feed, which could pretty much just be RSS or ATOM.
• Related Content API, that takes as input some key terms or even full text like AdSense, but instead of showing related Ads shows related stories, with links to your content.
• An interface to a collaborative filtering mechanism like the the Guardian's crowdsourced MP scandal spotter

Michael Morisy

241