from the teehee dept
This is the documentation for the upcoming SoylentNews API that I'm working on. It is currently live but it's possible it may cease to be that way. In the event that it doesn't though, I want it documented so people can actually start building against it right off.
Code is arranged with methods (m=foo) being the highest order of operation, each able to perform several ops (m=foo&op=bar, m=foo&op=baz). Each op requires or allows different arguments, depending on what is being done.
The top level methods are as follows:
The operations for each method are as follows:
latest - returns the latest 50 comments without argument or all comments since the comment id supplied in the argument "since". if "since" is not numeric, the latest 50 are returned. if since is too high, an empty json array is returned
post - posts a comment. sid, postersubj, posttype, reskey, and postercomment are required. sid may be numeric or in "14/08/07/1647258" form. preview=1 will return a json-encoded preview exactly as it would be included on the webpage for viewing. to reply to another comment, set pid = the comment to reply to's cid. I very much suggest you use a POST request here or it will be a huge pain to fill out postercomment properly and you will be limited by GET request max length. posttype is as follows: 1 Plain Old Text, 2 HTML, 3 Extrans (HTML tags to text), 4 Code reskey comes from a previous call to the m=comment&op=reskey op ten seconds are required between reskey creation and use so do a reskey creation call before allowing the user to enter data
latest - returns the latest 10 stories. optionally takes "limit" as an argument for the number of stories returned, which may range from 1-50. You may also specify "tid" as an argument. Behavior is however strange currently. If tid is the tid of a topic, you will get stories of that topic from every nexus; if tid belongs to a nexus, you will get stories of every topic within that nexus. This needs to be changed but it would require changing the main site as well.
login - Logs you in, duh. Takes nick and pass as mandatory arguments. Currently returns the cookie value. DO NOT USE THE COOKIE VALUE. Use the proper cookie returned in the headers as this will change to a success/failure check only soon. You should also probably do this via POST for security reasons.
Syntax: ~api [%argument1%=%value1% %argument2%=%value2%] [/%element%]
There can be as many argument=value pairs as you like, and the element is optional and corresponds to a key in the json structure
~api m=user op=get_uid nick=The Mighty Buzzard /uid
The element may also contain forward-slashes that correspond to array levels, allowing you to drill down into an array structure to retrieve a specific piece of data. For example, to get the uid of the latest comment:
~api m=comment op=latest /0/uid