Official NodeJS and BrowserJS client for the Asana API
Install with npm:
npm install asana --save
Include the latest release directly from GitHub.
nodeifywhich takes a callback as parameter. For generators and streams, co and highland also support promises respectively. Beyond that, other major libraries such as mongoose, mocha, and elastic search (which uses bluebird) also support promises.
To do anything, you'll need always an instance of an
with your preferred authentication method (see the Authentication section below
for more complex scenarios) and other options.
The most minimal example would be as follows:
var asana = require'asana';var client = asanaClientcreateuseAccessToken'my_access_token';clientusersmethenconsole.logme;;
All resources are exposed as properties of the
Asana.Client instance (e.g.
client.workspaces). See the developer documentation for docs on each of them.
This module supports authenticating against the Asana API with either a Personal Access Token or through OAuth 2.0.
var client = AsanaClientcreateuseAccessToken'personal_access_token';
Authenticating through OAuth2 is preferred. There are many ways you can do this.
In all cases, you should create a
Client that contains your app information. The values in the below snippet should be substituted with the real properties from your application's settings.
var client = AsanaClientcreateclientId: 123clientSecret: 'my_client_secret'redirectUri: 'my_redirect_uri';
If you have a plain bearer token obtained somewhere else and you don't mind not having your token auto-refresh, you can authenticate with it as follows:
If you obtained a refresh token (from a previous authorization), you can use it together with your client credentials to authenticate:
var credentials =// access_token: 'my_access_token',refresh_token: 'my_refresh_token';clientuseOauthcredentials: credentials;
examples/oauth/webserver for a working example of this.
Whenever you ask for a collection of resources, you will receive a
object which gives you access to a page of results at a time. You can provide
a number of results per page to fetch, between 1 and 100. If you don't provide
any, it defaults to 50.
clienttasksfindByTagtagId limit: 5 thenconsole.logcollectiondata;// [ .. array of up to 5 task objects .. ];
Collection has a few useful methods that can make them
more convenient to deal with.
To get the next page of a collection, you do not have to manually construct
the next request. The
nextPage method takes care of this for you:
To automatically fetch a bunch of results and have the client transparently
request pages under the hood, use the
clienttasksfindByTagtagIdthen// Fetch up to 200 tasks, using multiple pages if necessarycollectionfetch200thenconsole.logtasks;;;
You can also construct a
stream from a collection. This will transparently
(and lazily) fetch the items in the collection in pages as you iterate
In any request against the Asana API, there a number of errors that could
arise. Those are well documented in the Asana API Documentation, and
are represented as exceptions under the namespace
Various examples are in the repository under
examples/, but some basic
concepts are illustrated here.
var Asana = require'asana';var util = require'util';// Using the API key for basic authentication. This is reasonable to get// started with, but Oauth is more secure and provides more features.var client = AsanaClientcreateuseBasicAuthprocessenvASANA_API_KEY;clientusersmethenvar userId = userid;// The user's "default" workspace is the first one in the list, though// any user can have multiple workspaces so you can't always assume this// is the one you want to work with.var workspaceId = userworkspaces0id;return clienttasksfindAllassignee: userIdworkspace: workspaceIdcompleted_since: 'now'opt_fields: 'id,name,assignee_status,completed';then// There may be more pages of data, we could stream or return a promise// to request those here - for now, let's just return the first page// of items.return responsedata;filterreturn taskassignee_status === 'today' ||taskassignee_status === 'new';thenconsole.logutilinspectlistcolors: truedepth: null;;
The code is thoroughly documented with JsDoc tags. The Official Asana Documentation is a great resource since this is just a thin wrapper for the API.
Feel free to fork and submit pull requests for the code! Please follow the existing code as an example of style and make sure that all your code passes lint and tests. For a sanity check:
git clone email@example.com:Asana/node-asana.gitcd node-asananpm installnpm test
The specific Asana resource classes (
Task, etc) are
generated code, hence they shouldn't be modified by hand. See the asana-api-meta repo for details.
Repo Owners Only. Take the following steps to issue a new release of the library.
masterbranch and commit them.
gulp bump-feature, or
git push origin master --tags
Travis CI will automatically build and deploy the tagged release.