Integrating Trello with your web app

A better path to building on top of Trello.

Image by Sebastien Gabriel on unsplash.com

To begin, first let’s set the general context of this discussion:

1. You’re building or intend to build an application (web).
2. You want to be able to access your users’ resources (protected resources) in Trello.

For your application to access and/or perform any operation on users protected resource on the user’s behalf, the user must first grant your application the privilege(s) to do so (Authorization).

Trello provides two(2) major options for achieving this:

1. Use Trello Client.js lib.
2. Use Basic OAuth.

Option 1: Trello Client.js

This is the most basic, easier to implement method — and just as the name implies, it is targeted at client applications. So if you’re building a simple web client then this may be the option for you.

For a walkthrough on how to implement option (1) visit here

From that walkthrough, you might notice that to use client.js, you have to add <script src=”https://trello.com/1/client.js?key=[appkey]"></script> to your root page. Note that a Trello user can only have one appkey and at the moment Trello does not provide an easy away to reset this.

Here is my take:

1. Having appkey at the front-end as required by Trello’s Client.js lib appears not to be a good practice. At least in my opinion. On the side of the developer, it practically gives your identity away. Anyone with this key “is you”. So a malicious developer can copy your key over to their own application and whatever he/she does with it, to Trello it is you.
2. Client.js lib, when loaded successfully, appends a Trello object to the global scope in the browser (window object). The security implication is wide and far reaching for a user who grants access to his/her protected resource as this Trello object depending on the granted privileges, becomes a free pass to the user’s resource after authorization. Frankly, Client.js should be used only in demos or client apps targeted at limited internal users and not in production client apps targeted at larger public users.

Trello object appended to global scope in browser

Option 2: Basic OAuth

Let’s kick-off exploring this option with some very vital information provided by Trello here.

Points worthy of note from that information:

1. Trello API supports basic OAuth.
2. In addition to your appkey, you’ll need your application secret (used to sign your requests).
3. The URLs below:

https://trello.com/1/OAuthGetRequestToken
https://trello.com/1/OAuthAuthorizeToken
https://trello.com/1/OAuthGetAccessToken

If you’re already very comfortable with consuming API’s, OAuth, and CoffeeScript and all you want is just some heads-up then I’ll suggest you just go ahead to sample code.However, if you are relatively new or don’t mind seeing something slightly more elaborate with some idiosyncrasies of mine here and there then come along for this ride. Hopefully, you’ll find it enjoyable.

For this demo we’ll use:

1. Nodejs
2. OAuth package. You can find this in npm.

First question: What resources do we want to access?

Say the users,

1. Info.
2. Boards.
3. Board lists.
4. Cards on boards.

This forms a set of queries that we’ll be sending to Trello. To keep it modular let’s create a node module for this.

Queries.js — Modular and promisified Trello queries implemented in NodeJS.

Quick explanation:

1. We created a function constructor called Query with one property called URI and four member methods getUserInfo, getUserTrelloBoards, getBoardLists and getCardsOnList corresponding respectively to the four user’s resources we want to access.
2. Note that each member methods accepts a single parameter(object) consisting of the access token, access token secret, and id of the resource we want to access. This access token and access token secret we’ll get to in a moment.

You may have noticed that in Queries.js above, we required an external module trelloAuth. This module is actually responsible for making Http calls to Trello. So now let’s build that module. Make sure to keep both files in the same directory.

To begin, first we need to answer the questions, why this module and what exactly will it be doing for us?

1. We need something to handle the Basic OAuth flow and this module will do that for us.
2. Secondly, as a path of the OAuth flow, we’ll obtain tokenKey pairs at different stages and we’ll need to cache them somewhere they can be retrieved when we need them. This module will handle this caching and retrieval as well.
3. This module will also serve as a wrapper around npm OAuth package that will be making Http calls to Trello end-points.

In case you’re not familiar with basic OAuth flow or need a refresher, quickly see this. Welcome back. Below is a diagram depicting the OAuth flow more specific to our discussion.

Basic OAuth flow.

Basic OAuth flow. We need our application info as well. Which are: appName, appkey and appsecret and a url for Trello to callback and return the user to our application after authorization. So let’s group this application info into a separate module.

appConfig module — in NodeJS

With those out of the way, let’s build.

Trello OAuth module. Handles token request and caching. Before use, in prod. env. refactor to cache in an in-memory db (eg Redis).

At this point, let’s take a look at what we already have and what more we need.

1. We have Queries.js to fetch resources from Trello after authorization.
2. We have appConfig.js with appName and key/secret uniquely assigned by Trello.
3. We have trelloAuth.js to handle basic OAuth flow and token/token-secret pair caching.

We need a route module which will be exposed to the front-end (client app). This module will:

1. Initiate the back-end authorization operation when a user visits the front-end and indicates interest to log in with Trello.
2. This module will also implement the callBackUrl function referenced in appConfig.callbackUrl.
3. Will serve as a SINGLE POINT for sending queries to Trello. It means we will import our Query module here.

Let’s build.

Route module.

To make functions in trelloRoute.js reachable from the outside world (client application) via Http calls, we will setup a node Http server and create APIs to route Http requests to appropriate trelloRoute functions.

So let’s build the Http server.

Finally, let’s look back to see how far we’ve come.

1. We have our set of queries in Queries.js.
2. We have trelloAuth.js to handle basic OAuth flow involved in users granting read privilege to our app.
3. We have trelloRoute.js, a single point to trigger Trello querying as well as a window to accept requests from the server.
4. And finally, we have trelloApp.js where we defined the Http server with endpoints (APIs) to accept requests from the outside world (client app), channel requests to appropriate routes and in return, return responses to the client app.

An end-to-end use-case interaction sequence between the user, our application’s modules and Trello.

Acknowledgement: Linda Peng — Thanks for the reviews.