Announcing the Node.js API client

If you would have asked me a month ago if a Node.js client was on the planning board for the DNSimple API, I would have said no way. Node.js plays a small role at DNSimple, mostly through libraries that deal with static assets (such as Brunch).

We recognize that a lot of developers use Node.js though, and I wanted to see what life in node-land is like following the ES6 changes that were recently introduced to JavaScript. I'm happy to report that JavaScript has improved quite a bit since I last developed with it significantly, and these improvements made developing the Node.js wrapper for the DNSimple API happen much faster than I would have expected.

The DNSimple API Node.js client is now available on npm, the standard Node.js package manager.

The Story

A little over two weeks ago I fired up MacVim and started taking a look at some other API clients written for node.js. Specifically I used the Stripe Node wrapper as inspiration. Given that I knew I wanted a official node.js library, I made my first commit to start playing around. I wanted to ensure I was able to write well-tested code and that I would understand the various dependencies I would need.

When writing a client for the DNSimple API, the first call to implement is to the whoami endpoint. This endpoint returns a bit of information about the current authentication context, thus requiring successful authentication and a call to the endpoint. For the first take I implemented the call using a style similar to what I saw in the Stripe Node wrapper, however I quickly switched to using ES6 classes as it made the code much cleaner and easier to understand. You can see the first version in the file lib/dnsimple/identity.js and compare it to the second version. At that point the whoami endpoint worked and I began adding additional endpoints.

Another interesting point in the development of this library was the switch to use Promises exclusively. If you haven't used promises yet, then you should consider it. The resulting code is much cleaner for both the caller and the callee in many cases. I had not used promises prior to this, so initially I had to wrap my head around how it was supposed to be used, but once I understood the basics I was able to update the entire library to rely on Promises as the return type for all methods that result in an external network call. Switching to promises also made it easier to make the options object that is passed to all methods actually optional!

Finally, there is string interpolation, another ES6 feature, that also helps make the code cleaner. No more concatenating a bunch of strings and variables when it can be handled more clearly with interpolation.

Getting started

First, install the client via npm:

npm install dnsimple

That will get you the latest stable version of the client through npm. Alternatively you can install the latest code from our repository on Github with:

npm install dnsimple/dnsimple-node

You will also need a token to authenticate with API. You can choose one of the supported methods. If you want to do the OAuth dance, the client has some helpers to make your life easier.

You can use the authorizeUrl function to generate the URL to start the dance:

var client = require('dnsimple')({
  accessToken: process.env.TOKEN,
  baseUrl: 'https://api.sandbox.dnsimple.com',
});

var state     = 'some-random-state';
var clientId  = process.env.OAUTH_CLIENT_ID;

dnsimple.oauth.accessUrl(clientId, {state: state});
// > https://sandbox.dnsimple.com/oauth/authorize?client_id=a1b2c3d4e5&state=some-random-state&response_type=code

And to obtain the access token:

var code          = '0123456789'; // the code from the callback
var state         = 'some-random-state';
var clientId      = 'a1b2c3d4e5';
var clientSecret  = 'the-app-secret';

dnsimple.oauth.exchangeAuthorizationForToken(code, clientId, clientSecret, {state: state}).then(function(response) {
  // the authorization info including the access token
  console.log(response.data);
}, function(error) {
  // handle error
});

Once you have the token you can start using the endpoints that require authentication:

client.identity.whoami().then(function(response) {
  console.log(response);
}, function(error) {
  // handle error
});

You can also add domains to DNSimple so you can manage them:

client.domains.create(accountId, 'example.com').then(function(response) {
  console.log(response);
}, function(error) {
  // handle error
});

Or if you want to register a domain that is available for registration:

client.registrar.register(accountId, 'example.com', {registrant_id: registrantId}).then(function(response) {
  console.log(response);
}, function(error) {
  // handle error
});

Where the registrant_id is the id of one of the contacts in your DNSimple account. Of course you can also add and manage contacts via the API.

Once your domain is registered, you can add new records to your domain using the zones API:

client.zones.createZoneRecord(accountId, 'example.com', {name: '', type: 'ALIAS', content: 'muchawesome.herokuapp.com', ttl: 600}).then(function(response) {
  console.log(response);
}, function(error) {
  // handle error
});

With this launch, you now have access to all of the endpoints described on the DNSimple v2 API developer documentation as well as a committment from the DNSimple team that we will continue adding functionality to this API client as it becomes available.

The DNSimple API Node.js client is now available on npm, the standard Node.js package manager. You can download and start using it today. Here are more examples that you may want to take a look at. If you want to experiment, we also provide a Sandbox environment where you can create a free account and play with our API client yourself.

Future Plans

2016 has been the year of the API at DNSimple. We have been working super hard on version 2 and the official clients for it. We even ate our own dog food and built some cool tools on top of it. We have more in store for this year and 2017 that will demonstrate the power of a robust API for managing your domains, so stay tuned!

Share on Twitter and Facebook

Anthony Eden

I break things so Simone continues to have plenty to do. I occasionally have useful ideas, like building a domain and DNS provider that doesn't suck.