RedditKit.rb

RedditKit.rb is a reddit API wrapper, written in Ruby.

Documentation

http://rdoc.info/gems/redditkit/

Installation

Add this to your Gemfile:

gem 'redditkit', '~> 1.0.1'

Or install it directly:

gem install redditkit

Getting Started

RedditKit.rb is structured closely to the wonderful Octokit.rb and Twitter gems. If you're familiar with either of those, you'll feel right at home here. You can find the project's documentation on the RedditKit website.

RedditKit.rb is used through either the RedditKit module, or RedditKit::Client objects, like so:

Module usage:

RedditKit.sign_in 'username', 'password'
subreddits = RedditKit.subscribed_subreddits

Instance method usage:

client = RedditKit::Client.new 'username', 'password'
subreddits = client.subscribed_subreddits

Using RedditKit.rb at the module level allows you to use a single account without having to keep track of RedditKit::Client instances. Working at the instance method level makes it possible to use multiple accounts at once, with one client object per account.

RedditKit.rb doesn't have any built-in rate limiting. reddit's API rules require that you make no more than 30 requests per minute and try to avoid requesting the same page more than once every 30 seconds. You can read up on the API rules on their wiki page.

Authentication

client = RedditKit::Client.new 'username', 'password'
client.signed_in? # => true

More Examples

Fetch a user and check their link karma:

user = RedditKit.user 'samsymons'
puts "#{user.username} has #{user.link_karma} link karma."

Subscribe to a subreddit:

authenticated_client = RedditKit::Client.new 'samsymons', 'password'
authenticated_client.subscribe 'ruby'

Upvote the top post in a subreddit:

posts = authenticated_client.posts 'programming', :category => :top, :time => :all
authenticated_client.upvote posts.first

Send private messages:

authenticated_client.send_message 'How are you?', 'amberlynns', :subject => 'Hi!'

Pagination

Some RedditKit.rb methods accept pagination options and return RedditKit::PaginatedResponse objects upon completion. These options allow you to, for example, limit the number of results returned, or fetch results before/after a specific object.

RedditKit::PaginatedResponse forwards its enumeration methods to its results array, so you can iterate over it like you would with a standard array.

paginated_response = RedditKit.front_page

paginated_response.each do |link|
  # Do something with each link.
end

Configuration

You can configure various aspects of RedditKit.rb's operation, including its default API endpoint and user agent, by setting attributes on RedditKit::Client.

You should set your user agent to the name and version of your app, along with your reddit username. That way, if you ever have a buggy version of your app abusing the API, the reddit admins will know who to contact.

Contributing

Debugging

Because RedditKit.rb is built atop Faraday, you can modify its middleware stack to add new behaviour. This is particularly handy for debugging as you can turn on Faraday's response logger.

RedditKit.middleware = Faraday::Builder.new do |builder|
  builder.use Faraday::Request::UrlEncoded
  builder.use RedditKit::Response::RaiseError
  builder.use RedditKit::Response::ParseJSON
  builder.use Faraday::Response::Logger  
  builder.adapter Faraday.default_adapter
end

Writing Tests

Tests assume the presence of a .env file at the project's root. This file should contain the following three environment variables:

• REDDITKIT_TEST_USERNAME The username of a reddit account dedicated solely to testing.
• REDDITKIT_TEST_PASSWORD The password for the reddit account.
• REDDITKIT_TEST_SUBREDDIT A subreddit for which the provided reddit account has admin privileges. This subreddit should be also be dedicated to testing as the test suite will run many different methods on it, creating & deleting various resources.

Requirements

Ruby 1.9.3 and Ruby 2.0.0 are officially supported.

Need Help?

Open an issue, or hit me up on Twitter.

License

Copyright (c) 2013 Sam Symons (http://samsymons.com/)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.