ApiDocs

Development - parent

Foreword

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.

Layout

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.

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

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

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