From SoylentNews
Revision as of 21:11, 12 November 2014 by The Mighty Buzzard (talk | contribs) (typos)

Jump to: navigation, search

Development - parent


This is the documentation for the upcoming SoylentNews API that I'm working on. It is by no means live and it's possible it may never become that way. In the event that it does though, I want it documented so people can actually start building against it right off.

As of now the API is read only and does not feature authorization or anything that should require the code to auth.


Code is arranged with methods (m=foo) being the highest order of operation, each able to preform 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
  • post - posts a comment. sid, postersubj, posttype, 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
    • 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
  • 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