|
This document is for review only. The API it describes has been deployed, but is not quite ready for testing. Real Soon Now. The JSON API makes it possible to program anything the my.reallysimple.org website does in JavaScript or in other JSON-compatible programming languages. It also makes it possible to create compatible servers running in other environments. The API provides glue that connects the data with the UI. Here are the basic concepts of the API. 1. There are users. Users have feeds and feeds have posts. 2. The username and password are specified through HTTP basic authentication. 3. Each endpoint returns a JSON value. If there's an error, two values are returned: error, a string that explains the error, and code, a number that identifies the class of error. The possible values for code are: 401, unauthorized; 404, not found; and 500, internal error. 4. For my server, the address of each endpoint begins with http://my.reallysimple.org/api/. On other servers the URL will be something different. Here's a list of each of the endpoints and an explanation of what it does and what is returned. http://my.reallysimple.org/api/newPost?feed=noHeed.xml&title=Hello&link=http%3A%2F%2Fscripting.com%2F&description=Just-a-test feed -- the name of the feed you want to add the post to. title -- the title of the post, optional, if not specified, the empty string. link -- the address the post points to, if not specfied, the empty string. description -- a brief description of the article being linked to (assuming there is a link) or the body of the post (if there is no link). enclosure -- optional, an http link to a media file or image that's the enclosure for the post. http://my.reallysimple.org/api/editPost?feed=linkblog.xml&idPost=12&title=Everything%20is%20DEAD feed -- the name of the feed you want to add the post to. idPost -- the ID of the post you want to edit. title -- optional, replaces the title of the post. If not present, the title is unchanged. link -- optional, replaces the link of the post. If not present, the link is unchanged. description -- optional, replaces the description of the post. If not present, the description is unchanged. enclosure -- optional, an http link to a media file or image that's the enclosure for the post. http://my.reallysimple.org/api/newFeed?feed=noHeed.xml&title=MyNewFeed http://my.reallysimple.org/api/setFeedPrefs?feed=noHeed.xml&title=NY%20Mets%20Links&docs=http://hello.dolly/hello.html feed -- the name of the feed whose prefs you want to set. title -- the title of the feed, optional. If not specified, no change. link -- the link associated with the feed. If not specified, no change. description -- the description of the feed. If not specified, no change. language -- the language of the feed. If not specified, no change. docs -- the docs link for the feed. If not specified, no change. http://my.reallysimple.org/api/getFeedHistory?feed=wikileaks.xml&count=5 Here's an example of a feed produced by my.reallysimple.org. In the database there is no limit on the number of items in a feed. When the feed is built, i.e. turned into RSS, there is a limit of 100 items. This is not a limit of the protocol, rather a limit of this implementation. If you would rather place a different limit on the number of items in the RSS, please go ahead. When I build a feed it is also stored in a calendar-structured archive. So if you post no more than 100 items per day, all your items will be backed up in the archive. For example, here is the archived version of my example feed for January 5. Note that these are not all the posts from January 5, rather a snapshot of the feed taken the last time it was built on January 5. 1/17/11 by DW -- on getFeedPrefs, it now returns a "cloud" value that reflects the cloud prefs for the feed. Assumes the protocol is http-post. The cloud is formed into a URL, for example: http://rpc.rsscloud.org:5337/rsscloud/pleaseNotify |
 |
© Copyright 1997-2011 Dave Winer. Last update: Monday, January 17, 2011 at 7:17 PM Eastern. Last build: 12/12/2011; 12:55:13 PM. "It's even worse than it appears."
Previous / Next