From SoylentNews
Revision as of 14:36, 19 August 2015 by The Mighty Buzzard (talk | contribs) (story ops)

Jump to: navigation, search

Development - parent


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:

  • 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
    • not yet implemented
  • auth
    • not yet implemented
  • default
    • any other method currently returns an empty 200 status. error text would not be a bad idea though.


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.
    • 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:
    2=Answers, 4=Slash, 5=Code, 6=News, 9=Hardware, 10=/dev/random, 11=OS, 12=Business, 13=Mobile, 14=Science, 15=Security, 16=Software, 18=Techonomics, 19=Career & Education An op needs to be added to be able to pull story topics for when they change.
    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 (dev only)
    • https://soylentnews.org/api.pl?m=story&op=nexuslist
  • 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


  • 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


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