Reddit Base

A minimal reddit API client for Ruby.

Motivation

Managing major versions of an API client can be tricky, especially when the API us unversioned, inconsistent and outside of your control.

This client library aims to provide minimal support for the reddit API, reducing the need for frequent breaking changes and to act as the backbone for more other higher-level API clients.

Installation

Via Rubygems:

gem install reddit-base

Or in your Gemfile with Bundler:

gem reddit-base

What it Does

Authentication (user/password, cookie, OAuth2 access token).
Rate limiting.
Modhash handling (reddit's CSRF protection).
JSON coersion.
Forwarding..
Multipart POST.
Reddit error wrapping.

What it Doesn't

OAuth2 token negotiation.
Parsing of Reddit "Things" and "Kinds."
Parsing of common attributes like dates and times.
HTML entity decoding (beware of "body" and "selftext").

Usage

Retrieve the JSON for a particular endpoint:

require 'reddit/base'

client = Reddit::Base::Client.new(user: USERNAME, password: PASSWORD)
client.get('/r/AskReddit')

Making a new self post:

require 'reddit/base'

client = Reddit::Base::Client.new(user: USERNAME, password: PASSWORD)
client.get('/r/AskReddit') # Need to make at least one GET request to retrieve a modhash.
client.post('/api/submit', kind: 'self', sr: SUBREDDIT, title: 'Hello,', text: 'World!')

Authentication

Examples:

# Username and password.
client = Reddit::Base::Client.new(user: USERNAME, password: PASSWORD)

# Cookie.
client = Reddit::Base::Client.new(cookie: COOKIE)

# OAuth2 access token.
client = Reddit::Base::Client.new(access_token: ACCESS_TOKEN)

File Uploads

For example, uploading an image to a subreddit you moderate:

image_upload = Reddit::Base::UploadIO.new('/path/to/your/image.png', 'image/png')
client.post('/api/upload_sr_img.json', r: SUBREDDIT, file: image_upload, header: 0, name: 'example'

Traversal

Client returns a type of Hashie::Mash so instead of:

client.get('/r/AskReddit')['data']['children']

You can do:

client.get('/r/AskReddit').data.children

As a bonus it also forwards any missed methods along to its data attribute, so you can take it a step further and just do:

client.get('/r/AskReddit').children

Frequently Asked Questions

Why do some requests 403 the first time but succeed when repeated?

The most common cause is that you're attempting to access something private and your modhash hasn't been set yet. Try making a request against a public endpoint (e.g. client.get('/r/AskReddit')) at the start of each session.

Contributors

Maintainer: Daniel O'Brien