Migration guide: v3

Advantages of using the v3 Node.js SDK

• More frequent updates - Our latest Node SDK benefits from automation that allows us to quickly roll out updates as the Asana API evolves. This means you can take advantage of the latest features and endpoints through the Node SDK soon after their release.
• Using native, modern JavaScript features - Our previous Node SDKs leveraged polyfills for functionality that is now natively supported (like Promises). The latest SDK versions take advantage of these native implementations and are more compatible with modern Node runtimes.
• Standard interface - Our latest Node SDK is built using tools which are common in the industry. It may be similar to SDKs you’ve used with other services.

Differences between v1 and v3

Instantiating the client

With the v3 Node SDK, you set your API access token once and then create an instance for each resource you wish to access (tasks, projects, etc).

Once you create the client instance, most of the method names should be the same. The full list is here in the client’s GitHub repository.

v3

const Asana = require('asana');

let client = Asana.ApiClient.instance;
let token = client.authentications['token'];
token.accessToken = '<YOUR_ACCESS_TOKEN>';

let usersApiInstance = new Asana.UsersApi(); // instance to access users

usersApiInstance.getUser("me").then(function(me) {
  console.log(me);
});

v1

const asana = require('asana');
const client = asana.Client.create().useAccessToken('<YOUR_ACCESS_TOKEN>');
client.users.me().then(function(me) {
  console.log(me);
});

Pagination

The v3 Node SDK supports the nextPage method for pagination, but does not yet support the fetch or stream methods. To use nextPage, you must also explicitly set a limit where before there was a default of 50.

v3

// Fetching the next page
tasksApiInstance.getTasks({ limit: 50 }).then(firstPage => { // set an explicit limit
  console.log(firstPage.data);
  firstPage.nextPage().then(secondPage => {
    console.log(secondPage.data);
  });
});

// Fetching up to 200 tasks with a page size of 50
tasksApiInstance
  .getTasks({ limit: 50, project: "1199684513975168" })
  .then(async (firstPage) => {
    let results = firstPage.data;

    // Get the next page
    let nextPage = await firstPage.nextPage();
    pageIndex = 2;

    // Keep fetching until there are no more results or
    // 200 results have been fetched
    while (nextPage.data && pageIndex <= 4) {
      results = results.concat(nextPage.data);
      console.log(pageIndex, results.length);
      // Get the next page
      nextPage = await nextPage.nextPage();
      pageIndex += 1;
    }
  });

v1

// Fetching the next page
client.tasks.findAll({ limit: 50 }).then((firstPage) => {
  console.log(firstPage.data);
  firstPage.nextPage().then((secondPage) => {
    console.log(secondPage.data);
  });
});

// Fetching up to 200 tasks with a page size of 50
client.tasks
  .findAll({ limit: 50, project: "1199684513975168" })
  .then((collection) => {
    collection.fetch(200).then((tasks) => {
      console.log(tasks);
    });
  });

OAuth grant flow

The V1 Node SDK managed the OAuth grant flow. The V3 SDK simply takes a Bearer token. You can use a standard library to manage the OAuth grant flow (recommended) or implement it yourself.

This page has a list of common libraries for JavaScript and a code sample which you can use to get started.

Adding headers to requests

V3

const Asana = require('asana');

let client = Asana.ApiClient.instance;
let token = client.authentications['token'];
token.accessToken = '<YOUR_ACCESS_TOKEN>';

// Add asana-enable header for the client
client.defaultHeaders['asana-enable'] = 'new_goal_memberships';

V1

const asana = require('asana');
const client = asana.Client.create().useAccessToken('<YOUR_ACCESS_TOKEN>');

asana.Client.create({"defaultHeaders": {"asana-enable": "new_goal_memberships"}});

When is it appropriate to upgrade?

If you have an application which is working and rarely updated, it might not be worth the time and effort to update to the latest SDK version. Here are some scenarios where it might make sense to update:

• Regularly updated applications - If you continuously add features to your application as new Asana capabilities become available, updating to the latest version is an up front investment that may make it easier to quickly update your application in the future. The new version will also often get new Asana features before the old version.
• New development - If you are starting a new project that uses a template as a starting point, consider updating your template to use the latest SDK. This way, you’ll be ready to make use of new Asana features and SDK bug fixes once they’re available.

Will I be forced to upgrade?

No. You can continue to use the Asana v1 Node SDK, but it will no longer receive new features as the Asana API evolves.