Scripting News: JSON API for my.reallysimple.org

Home > Archive > 2011 > January > 8

JSON API for my.reallysimple.org

By Dave Winer on Saturday, January 08, 2011 at 7:52 PM.

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.

feedList

http://my.reallysimple.org/api/feedList

No parameters.

Returns a list of names of feeds.

newPost

http://my.reallysimple.org/api/newPost?feed=noHeed.xml&title=Hello&link=http%3A%2F%2Fscripting.com%2F&description=Just-a-test

Parameters

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.

Returns

All the attributes of the new post, including its ID, in idPost.

editPost

http://my.reallysimple.org/api/editPost?feed=linkblog.xml&idPost=12&title=Everything%20is%20DEAD

Parameters

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.

Returns

All the attributes of the updated post.

deletePost

http://my.reallysimple.org/api/deletePost?feed=linkblog.xml&idPost=12

Parameters

feed -- the name of the feed.

idPost -- the ID of the post you want to delete.

Returns

An empty struct.

buildFeed

http://my.reallysimple.org/api/buildFeed?feed=linkblog.xml

Parameters

feed -- the name of the feed to be built.

Returns

feedUrl -- the URL of the newly-built feed.

Note

Until you build the feed the new posts, edits and deletions are just in the database, they are not reflected in the feed until its built.

newFeed

http://my.reallysimple.org/api/newFeed?feed=noHeed.xml&title=MyNewFeed

Parameters

feed -- the name of the feed to be created.

title -- the title of the new feed, optional. If not specified "My New Feed".

link -- the link associated with the new feed. If not specified http://my.reallysimple.org/.

description -- the description of the new feed. If not specified, the empty string.

Returns

An empty struct.

getFeedPrefs

http://my.reallysimple.org/api/getFeedPrefs?feed=noHeed.xml

Parameters

feed -- the name of the feed whose prefs you want to get.

Returns

A JSON struct containing the prefs.

setFeedPrefs

http://my.reallysimple.org/api/setFeedPrefs?feed=noHeed.xml&title=NY%20Mets%20Links&docs=http://hello.dolly/hello.html

Parameters

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.

Returns

An empty struct.

getFeedHistory

http://my.reallysimple.org/api/getFeedHistory?feed=wikileaks.xml&count=5

Parameters

feed -- the name of the feed to get the history for.

count -- the number of posts to get, if not specified, the default is 25.

Returns

A list of structs, each containing information about the posts.

Notes

The list is reverse-chronologic, the most recent post first.

This endpoint is used to display a list of posts that can be edited.

General notes

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.

Changes

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

Follow @davewiner

Previous / Next