Introducing Flutter

At GoSquared, we use the Twitter API to power our Twitter Search and Followers widgets. As a result we handle Twitter authentication for thousands of accounts. We need to ensure that the flow of authorising GoSquared with Twitter is as smooth as possible, and we need it to be easy for us to use the Twitter API to make requests to power our data.

If you’ve ever worked with the Twitter API or any other service that requires OAuth authentication, you’ll know how incredibly fiddly it can be to get the authentication flow set up. To have it working properly, you need the necessary client tokens, request tokens, verifiers and access tokens. Simple getting your head around all the tokens and keys is hard enough with secrets everywhere.

Enter Flutter. Flutter is a minimal node module designed to take the hassle out of handling the Twitter authentication flow, and also has helper methods for making authenticated requests. We’ve just open sourced it on GitHub and you can find the repository here.

Here’s an example of how to set up an authentication flow using Flutter’s default options:

var express = require('express');
var Flutter = require('flutter');

var flutter = new Flutter({
  consumerKey: 'MY CONSUMER KEY',
  consumerSecret: 'MY CONSUMER SECRET',
  loginCallback: 'http://my-host/twitter/callback',
  completeCallback: '/someUrl'
});

var app = express();

app.get('/twitter/connect', flutter.connect);

// URL used in loginCallback above
app.get('/twitter/callback', flutter.auth);

// Direct users to /twitter/connect to initiate oauth flow.

// Users will be redirected back here once they're authenticated
app.get('/someUrl', function(req, res){

  // credentials are stored on the request session so you
  // can access them here and store them or make requests
  var accessToken = req.session.oauthAccessToken;
  var secret = req.session.oauthAccessTokenSecret;

  // Make some API requests. Let's search for some bacon.
  flutter.API.get(
    'search/tweets.json',
    { q: 'bacon' },
    accessToken,
    secret,
    function(err, results) {
      console.log(results); // { statuses: [ { ...etc } ] }
    }
  );
});

There are plenty of other options you can specify – for example there are several callbacks you can specify to catch authentication errors or save the credentials as soon as they’re retrieved. Check out the README over at the GitHub repository for a full list of available options.

You can find other open source modules we’ve released here at GoSquared labs.