ApiDocs

Development - parent

Foreword

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.

Layout

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.

Methods

The top level methods are as follows:

• user
  • operations on users such as looking up a uid by nickname or vice versa
• comment
  • operations on comments like getting the latest or an entire discussion's comments
• story
  • operations on stories such as getting the latest or a single story
• journal
  • operations on journals such as getting the latest journal or a series of journals
• auth
  • logging in to the API
• default
  • any other method currently returns an empty 200 status. error text would not be a bad idea though.

Operations

The operations for each method are as follows:

user ops

• max_uid - takes no arguments and returns the highest user id.

  • https://soylentnews.org/api.pl?m=user&op=max_uid

• get_uid - takes "nick" as an argument and returns the uid associated or null if there is no such user.
  the following are all equivilent:

  • https://soylentnews.org/api.pl?m=user&op=get_uid&nick=The Mighty Buzzard

  • https://soylentnews.org/api.pl?m=user&op=get_uid&nick=The+Mighty+Buzzard

  • https://soylentnews.org/api.pl?m=user&op=get_uid&nick=The%20Mighty%20Buzzard

• get_nick - takes "uid" as an argument and returns the nickname associated or null if there is no such user.

  • https://soylentnews.org/api.pl?m=user&op=get_nick&uid=18

• get_user - takes "uid" as an argument and returns full public user information for the user

  • https://soylentnews.org/api.pl?m=user&op=get_user&uid=18

• default - any other op returns an empty 200 status. error text would not be a bad idea though.

comment ops

• 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

  • https://soylentnews.org/api.pl?m=comment&op=latest

  • https://soylentnews.org/api.pl?m=comment&op=latest&since=27700

• discussion - returns all comments in a discussion. takes "sid" as an argument. sid must be the numeric story id here unlike with m=story&op=single.
  returns an empty 200 on error. this should be fixed.

  • https://soylentnews.org/api.pl?m=comment&op=discussion&sid=1117

• single - returns a single comment specified by the "cid" argument.

  • https://soylentnews.org/api.pl?m=comment&op=single&cid=27698

• reskey - returns a reskey for later use in the post op. takes no arguments.

  • https://soylentnews.org/api.pl?m=comment&op=reskey

• 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

  • https://soylentnews.org/api.pl?m=comment&op=post&sid=1128&postersubj=chickenbutt&postercomment=man+who+cares+even+more&posttype=1&preview=1

  • https://soylentnews.org/api.pl?m=comment&op=post&sid=1128&postersubj=chickenbutt&postercomment=man+who+cares+even+more&posttype=1

  • https://soylentnews.org/api.pl?m=comment&op=post&sid=1128&postersubj=chickenbutt&postercomment=man+who+cares+even+more&posttype=1&pid=27719

• default - any other op returns an empty 200 status. error text would not be a bad idea though.

story ops

• 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.

  • https://soylentnews.org/api.pl?m=story&op=latest

  • https://soylentnews.org/api.pl?m=story&op=latest&limit=42

• single - returns a single story. takes "sid" as an option. may be in the form of either sid=14/08/07/1647258 or sid=832. returns an empty 200 on error.

  • https://soylentnews.org/api.pl?m=story&op=single&sid=14/08/07/1647258

  • https://soylentnews.org/api.pl?m=story&op=single&sid=832

• pending - returns a json hash containing current submissions and pending stories. takes no arguments

  • https://soylentnews.org/api.pl?m=story&op=pending

• reskey - returns a reskey for later use in the post op. takes no arguments.

  • https://soylentnews.org/api.pl?m=story&op=reskey

• post - submit a story. subj, reskey, story, tid, sub_type, and primaryskid are required. name is optional.
  POST method is absolutely required for submissions
  primaryskid should be set to 1 until nexuses are working
  sub_type should be either "plain" or "html"
  reskey comes from a previous call to the m=story&op=reskey op
  name, subj, and story are up to you
  tid the topic and is the same as the values on submit.pl. Use the topiclist op to obtain a current list of topics.
  Twenty seconds are required between reskey creation and use so do a reskey creation call before allowing the user to enter data

  • no GET example will work, the POST method is required. https//soylentnews.org/api.pl?m=story&op=post&subj="..."&reskey='...'&story='...'&tid='...'&sub_type='...'&primaryskid='...'&name='...'

• nexuslist - returns an array of hashes containing data on every nexus

  • https://soylentnews.org/api.pl?m=story&op=nexuslist

• topiclist - returns an array of hashes containing data on every topic

  • https://soylentnews.org/api.pl?m=story&op=topiclist

• default - any other op returns an empty 200 status. error text would not be a bad idea though.

journal ops

• latest - returns the latest 20 journal entries. optionally takes "limit" and "uid" as arguments. limit specifies the number of results while uid specifies only entries by the user with that uid.
  limit may be anything in the range of 1-50.

  • https://soylentnews.org/api.pl?m=journal&op=latest

  • https://soylentnews.org/api.pl?m=journal&op=latest&limit=42

  • https://soylentnews.org/api.pl?m=journal&op=latest&uid=2

  • https://soylentnews.org/api.pl?m=journal&op=latest&uid=2&limit=3

• Single - returns a single journal entry specified by the argument "id". This is a journal id not a story id.

  • https://soylentnews.org/api.pl?m=journal&op=single&id=204

auth ops

• 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.

  • https://soylentnews.org/api.pl?m=auth&op=login&nick=The Mighty Buzzard&pass=ilikecheese

Errata

• The "uid" field data will always be truncated to only leading digits as part of slash internals. uid=18z becomes 18, uid=1z8 becomes 1, uid=z18 becomes a null value. This is expected behavior.

Related pages

SN API ideas

Example scripts

• PHP script used by the exec IRC bot: https://github.com/crutchy-/exec-irc-bot/blob/master/scripts/sn_api.php

Usage

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