Overview

There are a few things to know about the Reddit API before we get started.

Rules

  1. Clients must authenticate with OAuth2 to use the API
  2. Clients can make a maximum of 60 requests per minute
  3. Apps must identify themselves with a unique user-agent including app name, version number, target platform, and username.
  4. Do not use a fake user agent or the app may get banned.

Working with parameters

In the Reddit API all call parameters are sent as query parameters in the URL, even for calls that use an HTTP method other than GET (most notably POST). The only API calls where this isn't true are those used for authentication.

Getting back data

Data is sent back in XML format by default. To change it to JSON format you add the ".json" specifier at the end of the URL or, if the API call has a JSON parameter, set that parameter instead.

Listings and things

Many of Reddit's API methods return either a "listing" or a "thing". Listings, as the name suggests, are lists of objects (a list of threads or a thread's comments, for example). When requesting a listing you specify which part of a list of items you want with a set of common parameters we'll discuss later that allow you to slice the listing using a known element as a reference, limit the amount of elements you get back, use a count of threads you've seen instead, and get all listings even if you've chosen some to be hidden.

A "thing" is basically an object. There are several different types of "things" that Reddit can return. Examples include comments and accounts which have large data structures associated with them. You can view the documentation for things at the Reddit wiki.

Fullnames

A lot of the API methods use "fullnames" to identify posts, comments, and more. Think of them as IDs. Fullnames consist of a base-36 string called a "name" and a type identifer. You can view the details in the API documentation. You'll be working with fullnames a lot so it's good to know what they are now.