draw 0.4.6+1

A fully-featured Reddit API wrapper for Dart, inspired by PRAW.

DRAW: The Dart Reddit API Wrapper

DRAW, also known as the Dart Reddit API Wrapper, is a Dart package that provides simple access to the Reddit API. DRAW is inspired by PRAW, the Python Reddit API Wrapper, and aims to also maintain a similar interface.

Want to get involved? Check out how to contribute to get started!

Disclaimer: This is not an official Google product.

Installation

Installing DRAW is simple using Dart's package management system, pub. Instructions on how to import DRAW into your project can be found here. If you would prefer to live on the hemorrhaging-edge, methods to depend on a local copy of DRAW or on the Github repository can be found here.

Getting Started

Assuming you already have your Reddit OAuth credentials, getting started with DRAW is simple:

import 'dart:async';
import 'package:draw/draw.dart';

Future<void> main() async {
  // Create the `Reddit` instance and authenticated
  Reddit reddit = await Reddit.createScriptInstance(
    clientId: CLIENT_ID,
    clientSecret: SECRET,
    userAgent: AGENT_NAME,
    username: "DRAWApiOfficial",
    password: "hunter12", // Fake
  );

  // Retrieve information for the currently authenticated user
  Redditor currentUser = await reddit.user.me();
  // Outputs: My name is DRAWApiOfficial
  print("My name is ${currentUser.displayName}");
}

This simple example is a great way to confirm that DRAW is working and that your credentials have been configured correctly.

Web Authentication

To authenticate via the Reddit authentication page, the web authentication flow needs to be used. This requires that a web application is registered with a valid Reddit account, which provides a client-id and a client-secret. As part of this process, a redirect URL is associated with the registered web application. These three values are all that is needed to complete the web authentication flow.

Here is a simple example of how to use web authentication with DRAW:

import 'package:draw/draw.dart';

main() async {
  final userAgent = 'foobar';
  final configUri = Uri.parse('draw.ini');

  // Create a `Reddit` instance using a configuration file in the
  // current directory.
  final reddit = await Reddit.createWebFlowInstance(userAgent: userAgent,
                                                    configUri: configUri);

  // Build the URL used for authentication. See `WebAuthenticator`
  // documentation for parameters.
  final auth_url = reddit.auth.url(['*'], 'foobar'));
  
  // ...
  // Complete authentication at `auth_url` in the browser and retrieve
  // the `code` query parameter from the redirect URL.
  // ...

  // Assuming the `code` query parameter is stored in a variable
  // `auth_code`, we pass it to the `authorize` method in the
  // `WebAuthenticator`.
  await reddit.auth.authorize(auth_code);

  // If everything worked correctly, we should be able to retrieve
  // information about the authenticated account.
  print(await reddit.user.me());
}

It is also possible to restore cached credentials in order to avoid the need to complete the web authentication flow on each run:

import 'package:draw/draw.dart';

// Provides methods to load and save credentials.
import 'credential_loader.dart';

main() async {
  final userAgent = 'foobar';
  final configUri = Uri.parse('draw.ini');

  // Load cached credentials from disk, if available.
  final credentialsJson = await loadCredentials();

  var reddit;

  if (credentialsJson == null) {
    reddit =
        await Reddit.createWebFlowInstance(userAgent: userAgent,
                                           configUri: configUri);

    // Build the URL used for authentication. See `WebAuthenticator`
    // documentation for parameters.
    final auth_url = reddit.auth.url(['*'], 'foobar');

    // ...
    // Complete authentication at `auth_url` in the browser and retrieve
    // the `code` query parameter from the redirect URL.
    // ...

    // Assuming the `code` query parameter is stored in a variable
    // `auth_code`, we pass it to the `authorize` method in the
    // `WebAuthenticator`.
    await reddit.auth.authorize(auth_code);

    // Write credentials to disk.
    await writeCredentials(reddit.auth.credentials.toJson());
  } else {
    // Create a new Reddit instance using previously cached credentials.
    reddit = await Reddit.restoreAuthenticatedInstance(
        userAgent: userAgent,
        configUri: configUri,
        credentialsJson: credentialsJson);
  }

  // If everything worked correctly, we should be able to retrieve
  // information about the authenticated account.
  print(await reddit.user.me());
}

Here's an example draw.ini suitable for web based authentication:

default=default
reddit_url='https://www.reddit.com'
oauth_url=https://oauth.reddit.com
redirect_uri=https://www.google.com
client_id=YOUR_CLIENT_ID_HERE
client_secret=YOUR_SECRET_HERE
userAgent=draw_testing_agent

Here the redirect URI is set to https://www.google.com, but you'll need to replace that with whatever redirect you have registered.

The format of draw.ini configuration files is very similar to that of praw.ini files used by PRAW, although there may be some minor differences due to the .ini parser used by DRAW.

License

DRAW is provided under a BSD 3-clause license. Copyright (c), 2017, the DRAW Project Authors and Google LLC.