digitalocean
Advanced tools
digitalocean-node is a library for nodejs to access the DigitalOcean v2 API.
npm install digitalocean --save
Every resource is accessed via an instance of the client. Please chose one of your tokens and use that where ever TOKEN is referenced. For example:
var digitalocean = require('digitalocean');
var client = digitalocean.client('TOKEN'); // See
// client.{ RESOURCE_NAME }.{ METHOD_NAME }
Every resource method accepts an optional callback as the last argument. For example:
client.account.get(function(err, account) {
console.log(err); // null on success
console.log(account); //
});
See below for more options in the callback.
Resource methods also return a promise. For example:
client.droplets.list().then(function(droplets) {
var droplet = droplets[0];
return client.droplets.snapshot(droplet.id);
}).then(function() {
console.log("created a snapshot of a Droplet!");
}).catch(function(err) {
// Deal with an error
});
All resources and actions are listed below, however, the general structure of the client follows the following pattern:
client.droplets.list(callback);
client.droplets.create(options, callback);
client.droplets.get(123, callback);
client.droplets.delete(123, callback);
client.droplets.powerOff(123, callback);
client.droplets.getAction(123, 456, callback);
DigitalOcean's Spaces is an S3-compatible object storage service. The API for spaces is a different schema at a different abstraction level (XML and actual file objects) than the normal "control" API. The good news is that it's interopable with lots of existing S3 clients, this is a node one.
You should be able to use Spaces similarly to:
var s3 = require('s3');
var client = s3.createClient({
s3Options: {
accessKeyId: "your spaces key from https://cloud.digitalocean.com/settings/api/tokens",
secretAccessKey: "your spaces secret from https://cloud.digitalocean.com/settings/api/tokens",
region: "nyc3",
endpoint: 'nyc3.digitaloceanspaces.com',
},
});
The DigitalOcean client depends on request, and options can be passed through (e.g. a proxy or user agent). For example:
var client = digitalocean.client('TOKEN', {
request: myInitializedRequestObject,
requestOptions: {
proxy: 'https://myproxy.com:1085',
headers: {
'User-Agent': 'foo'
}
}
});
Other options include:
var client = digitalocean.client('TOKEN', {
promise: MySpecialPromiseVersion, // defaults to Promise
decamelizeKeys: false // defaults to true
});
var client = digitalocean.client('TOKEN');
client.get('/account', {}, 200, 'account', function (err, status, body, headers) {
console.log(body); //json object
});
All callbacks will be passed:
For example:
client.account.get(function(err, account, headers, response) {
console.log("error: " + err);
console.log("account: " + account);
console.log("headers: " + headers);
console.log("response: " + response);
});
Promise results are the resource(s) returned by a successful response - a list response object, an individual object, or a blank object (for successful empty responses such as deletes). These objects have a special property, _digitalOcean that includes response information. For example:
// ...
.then(function(object) {
console.log(object); // =>
// {
// _digitalOcean: {
// statusCode: 204,
// body: {},
// headers: {}
// }
// }
})
Although the DigitalOcean API returns results from query endpoints in pages, this client abstracts that notion by lazily fetching subsequent pages when they are needed. This allows developers to easily handles fetching large lists of resources without having to manually paginate results and perform subsequent requests - adding a layer of convenience on top of what is a common limitation in REST based APIs. An example of using this is:
client.droplets.list(function(err, droplets) {
if (err) {
return console.error('Error fetching pages', err);
}
droplets.all(function(err, droplet) {
console.log(err, droplet);
});
var error = iterator.error()
if (error) {
console.log(error);
}
});
Note that the magic .length property on ListResponse is tied to the first page of results.
client.droplets.list(function(err, droplets) {
if (err) {
return console.error('Error fetching pages', err);
}
// Limited to original page only:
for (var i = 0, len = droplets.length; i < len; i++) {
console.log(droplets[i]);
}
});
Under the hood, this enumeration is handled by an iterator object, this can be accessed as well (it uses promises internally):
client.droplets.list(function(err, droplets) {
if (err) {
return console.error('Error fetching pages', err);
}
var iterator = droplets.iterator();
var iterable = iterator.next();
while(!iterable.done) {
iterable.value.then(function(value) {
console.log(value);
iterable = iterator.next();
});
}
// Check the error afterwards:
var error = iterator.error()
if (error) {
console.log(error);
}
});
If a function declares pagination parameters, then results from the function are arranged in pages. These arguments are:
The page argument is optional and is used to specify which page of objects to retrieve.
The perPage argument is also optional and is used to specify how many objects per page.
// Normal usage of function
client.droplets.list(callback); // Callback receives an array of first 25 issues
// Using pagination parameters
client.droplets.list(2, 100, callback); // Callback receives an array of second 100 issues
client.droplets.list(10, callback); // Callback receives an array of 25 issues from page 10
// Pagination parameters can be set with query object too
client.droplets.list({
page: 2,
per_page: 100
}, callback); //array of second 100 issues which are closed
To fetch all the pages of a resource, the pages must be traversed. For example, to fetch all Droplets:
getAllDroplets(function(allDroplets) {
console.log(allDroplets.length);
});
function getAllDroplets(callback, page, array) {
client.droplets.list(page, function(err, droplets, _, response) {
if (err) {
return console.error('Error fetching pages', err);
}
if (page == null) {
page = 1;
}
if (array == null) {
array = [];
}
array = array.concat(droplets);
// has no pages or has pages and has no last page
var isLastPage = response['links'] && (
!response['links']['pages'] ||
(response['links']['pages'] && response['links']['pages']['last'] === undefined)
);
if (!err && isLastPage) {
callback.call(this, array);
} else if (!err && !isLastPage) {
getAllDroplets(callback, page + 1, array);
} else {
// whoops, try again
getAllDroplets(callback, page, array);
}
});
};
Or Promise style:
getAllDroplets().then(function(allDroplets) {
console.log(allDroplets);
}).catch(function(err) {
console.log(err);
});
function getAllDroplets() {
var allDroplets = [];
function getDropletPage(page) {
if (page == null) {
page = 1;
}
return client.droplets.list(page)
.each(function(droplet) {
allDroplets.push(droplet);
})
.then(function(droplets) {
var links = droplets._digitalocean.body.links;
var isLastPage = links && (
!links.pages ||
(links.pages && links.pages.last === undefined)
);
if (isLastPage) {
return allDroplets;
} else {
return getDropletPage(page + 1);
}
});
}
return getDropletPage();
}
You can also check your rate limit status by calling the following.
client.droplets.list(function (err, account, headers, response) {
console.log(headers['ratelimit-remaining']); // 4999
console.log(headers['ratelimit-limit']); // 5000
console.log(headers['ratelimit-reset']); // Time in Unix Epoch, e.g. 1415984218
});
This library is also available as a single file built for usage in the browser at dist/digitalocean.js. It uses browserify to package all dependencies and output the built file. This file is updated and released to Bower for each release with the same version.
For example, using the built file at dist/digitalocean.js:
<html>
<head></head>
<body>
<script src="dist/digitalocean.js"></script>
<script>
var client = digitalocean.client('TOKEN');
client.account.get(function(_, account) {
console.log(account.uuid);
});
</script>
</body>
</html>
The following resources and actions correspond to the resources and actions documented on DigitalOcean's API. Some methods take an attributes argument, which is a plain JavaScript object, e.g. { email: 'foo@example.com' }, whose keys and appropriate values are also documented in DigitalOcean's API documentation.
var digitalocean = require('digitalocean');
var client = digitalocean.client('TOKEN');
client.account
client.account.get([callback])client.account.listSshKeys([page, perPage], [callback])client.account.listSshKeys([queryObject], [callback])client.account.createSshKey(attributes, [callback])client.account.getSshKey(sshKey.id, [callback])client.account.deleteSshKey(sshKey.id, [callback])client.account.updateSshKey(sshKey.id, attributes, [callback])For the latest valid account attributes, see the official docs.
var digitalocean = require('digitalocean');
var client = digitalocean.client('TOKEN');
client.actions
client.actions.list([page, perPage], [callback])client.actions.get([queryObject], [callback])client.actions.get(action.id, [callback])var digitalocean = require('digitalocean');
var client = digitalocean.client('TOKEN');
client.volumes
client.volumes.list([page, perPage], [callback])client.volumes.list([queryObject], [callback])client.volumes.get(volume.id, [callback])client.volumes.create(attributes, [callback])client.volumes.delete(volume.id, [callback])client.volumes.listActions([page, perPage], [callback])client.volumes.listActions([queryObject], [callback])client.volumes.getAction(volume.id, action.id, [callback])Methods resulting in an action:
client.volumes.attach(volume.id, parametersOrDropletId, [callback])client.volumes.detach(volume.id, [callback])client.volumes.resize(volume.id, parametersOrSizeGibabytes, region, [callback])For the latest valid volume attributes and action parameters, see the official docs.
var digitalocean = require('digitalocean');
var client = digitalocean.client('TOKEN');
client.certificates
client.certificates.list([page, perPage], [callback])client.certificates.list([queryObject], [callback])client.certificates.get(certificate.id, [callback])client.certificates.create(attributes, [callback])client.certificates.delete(certificate.id, [callback])For the latest valid certificate attributes, see the official docs.
var digitalocean = require('digitalocean');
var client = digitalocean.client('TOKEN');
client.domains
client.domains.list([page, perPage,] [callback])client.domains.list([queryObject,] [callback])client.domains.create(attributes, [callback])client.domains.get(domain.name, [callback])client.domains.delete(domain.name, [callback])client.domains.listRecords([page, perPage,] domain.name, [callback])client.domains.listRecords([queryObject,] domain.name, [callback])client.domains.createRecord(domain.name, attributes, [callback])client.domains.getRecord(domain.name, domainRecord.id, [callback])client.domains.deleteRecord(domain.name, domainRecord.id, [callback])client.domains.updateRecord(domain.name, domainRecord.id,, attributes, [callback])For the latest valid domain attributes, see the official docs. For the latest valid domain record attributes, see the official docs.
var digitalocean = require('digitalocean');
var client = digitalocean.client('TOKEN');
client.droplets
client.droplets.list([page, perPage,] [callback])client.droplets.list([queryObject,] [callback])client.droplets.get(droplet.id, [callback])client.droplets.create(attributes, [callback])client.droplets.delete(droplet.id, [callback])client.droplets.deleteByTag(tag.name, [callback])client.droplets.kernels(droplet.id, [page, perPage,] [callback])client.droplets.kernels(droplet.id, [queryObject,] [callback])client.droplets.snapshots(droplet.id, [page, perPage,] [callback])client.droplets.snapshots(droplet.id, [queryObject,] [callback])client.droplets.backups(droplet.id, [page, perPage,] [callback])client.droplets.backups(droplet.id, [queryObject,] [callback])client.droplets.neighbors(droplet.id, [page, perPage,] [callback])client.droplets.neighbors(droplet.id, [queryObject,] [callback])client.droplets.listActions(droplet.id, [page, perPage,] [callback])client.droplets.listActions(droplet.id, [queryObject,] [callback])client.droplets.getAction(droplet.id, action.id, [callback])Methods resulting in an action:
client.droplets.actionByTag(tag.name, actionType, [callback])client.droplets.reboot(droplet.id, [callback])client.droplets.powerCycle(droplet.id, [callback])client.droplets.shutdown(droplet.id, [callback])client.droplets.powerOff(droplet.id, [callback])client.droplets.powerOn(droplet.id, [callback])client.droplets.passwordReset(droplet.id, [callback])client.droplets.enableIpv6(droplet.id, [callback])client.droplets.enableBackups(droplet.id, [callback])client.droplets.disableBackups(droplet.id, [callback])client.droplets.enablePrivateNetworking(droplet.id, [callback])client.droplets.snapshot(droplet.id, parametersOrName, [callback])client.droplets.changeKernel(droplet.id, parametersOrKernelId, [callback])client.droplets.rename(droplet.id, parametersOrHostname, [callback])client.droplets.rebuild(droplet.id, parametersOrImage, [callback])client.droplets.restore(droplet.id, parametersOrImageId, [callback])client.droplets.resize(droplet.id, parametersOrSizeSlug, [callback])For the latest valid droplet attributes, see the official docs. For the latest valid droplet action parameters, see the official docs.
var digitalocean = require('digitalocean');
var client = digitalocean.client('TOKEN');
client.floatingIps
client.floatingIps.list([page, perPage], [callback])client.floatingIps.list([queryObject], [callback])client.floatingIps.get(floatingIp.ip, [callback])client.floatingIps.create(attributes, [callback])client.floatingIps.delete(floatingIp.ip, [callback])client.floatingIps.listActions(floatingIp.ip, [page, perPage], [callback])client.floatingIps.listActions(floatingIp.ip, [queryObject], [callback])client.floatingIps.getAction(floatingIp.ip, action.id, [callback])Methods resulting in an action:
client.floatingIps.assign(floatingIp.ip, parametersOrDropletId, [callback])client.floatingIps.unassign(floatingIp.ip, [callback])For the latest valid attributes, see the official docs.
var digitalocean = require('digitalocean');
var client = digitalocean.client('TOKEN');
client.firewalls
client.firewalls.list([page, perPage], [callback])client.firewalls.list([queryObject], [callback])client.firewalls.get(firewall.id, [callback])client.firewalls.create(attributes, [callback])client.firewalls.delete(firewall.id, [callback])client.firewalls.update(firewall.id, attributes, [callback])client.firewalls.addDroplets(firewall.id, dropletIds, [callback])client.firewalls.removeDroplets(firewall.id, dropletIds, [callback])client.firewalls.addTags(firewall.id, tags, [callback])client.firewalls.removeTags(firewall.id, tags, [callback])client.firewalls.addRules(firewall.id, rules, [callback])client.firewalls.removeRules(firewall.id, rules, [callback])var digitalocean = require('digitalocean');
var client = digitalocean.client('TOKEN');
client.images
client.images.list([page, perPage], [callback])client.images.list([queryObject], [callback])client.images.get(image.id, [callback])client.images.delete(image.id, [callback])client.images.update(image.id, attributes, [callback])client.images.listActions(image.id, [page, perPage], [callback])client.images.listActions(image.id, [queryObject], [callback])client.images.getAction(image.id, action.id, [callback])Methods resulting in an action:
client.images.transfer(image.id, parametersOrRegionSlug, [callback])client.images.convert(image.id, [callback])For the latest valid attributes, see the official docs.
var digitalocean = require('digitalocean');
var client = digitalocean.client('TOKEN');
client.loadBalancers
client.loadBalancers.list([page, perPage], [callback])client.loadBalancers.list([queryObject], [callback])client.loadBalancers.get(loadBalancer.id, [callback])client.loadBalancers.update(loadBalancer.id, attributes, [callback])client.loadBalancers.delete(loadBalancer.id, [callback])client.loadBalancers.add(loadBalancer.id, parametersOrIds, [callback])client.loadBalancers.remove(loadBalancer.id, parametersOrIds, [callback])client.loadBalancers.createForwardingRules(loadBalancer.id, parametersOrRules, [callback])client.loadBalancers.deleteForwardingRules(loadBalancer.id, parametersOrRules, [callback])For the latest valid attributes and parameters, see the official docs.
var digitalocean = require('digitalocean');
var client = digitalocean.client('TOKEN');
client.regions
client.regions.list([page, perPage], [callback])client.regions.list([queryObject], [callback])var digitalocean = require('digitalocean');
var client = digitalocean.client('TOKEN');
client.sizes
client.sizes.list([page, perPage], [callback])client.sizes.list([queryObject], [callback])var digitalocean = require('digitalocean');
var client = digitalocean.client('TOKEN');
client.snapshots
client.snapshots.list([page, perPage], [callback])client.snapshots.list([queryObject], [callback])client.snapshots.get(snapshots.id, [callback])client.snapshots.delete(snapshot.id, [callback])var digitalocean = require('digitalocean');
var client = digitalocean.client('TOKEN');
client.tags
client.tags.list([page, perPage], [callback])client.tags.list([queryObject], [callback])client.tags.get(tag.name, [callback])client.tags.create(attributes, [callback])client.tags.update(tag.name, attributes, [callback])client.tags.tag(tag.name, [resources], [callback])client.tags.untag(tag.name, [resources], [callback])client.tags.delete(tag.name, [callback])For the latest valid attributes, see the official docs.
git checkout -b my-new-feature)git commit -am 'Add some feature')git push origin my-new-feature)npm test
Run:
npm run release:patch # or release:minor or release:major depending on the type of version bump
MIT
Based on the work of @pksunkara in octonode.
FAQs
nodejs wrapper for digitalocean v2 api
We found that digitalocean demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.