digital-ocean-api

Digital Ocean API (NodeJS/Javascript)

A thin wrapper for the Digital Ocean API (v2)

Table of Content

• Installation
• Usage
  • Callbacks
  • Errors
  • Paginated Resources
• Methods
• Todo
• License

Install

First get the package through NPM

npm install digital-ocean-api

Now set it up inside your application

var DigitalOceanApi = require('digital-ocean-api');

var api = new DigitalOceanApi({
  token: 'yourAccessToken'
});

Usage

Callbacks

All the methods utilize the same callback interface, except for the Paginator getPageRange method.

function(error, data) {};

Errors

Errors are created internally following the following pattern:

var error = new Error('message');
error.code = 'string_coded_error';
error.original = errorObject; // if applicable

These are the top-level errors (every callback can be return these errors)

• request_error: This is an error returned by the request function. When this error pops up, something went wrong with the request. This error will contain the original error as returned by your request function.
• request_implementation_error: When your implementation is flawed, this will most likely never occur.
• internal_server_error: When a status code between 500 and 599 is returned.
• response_error: When a status code between 400 and 499 is returned

Paginated resources

When a method accesses a paginated resource, you can pass along a callback and exhaust the entire resource, or you don't provide a callback in which you will get an instance of Paginator, a helper utility to more easily work with multi- page resources.

var paginator = api.listDroplets();

The paginator implements the following methods:

• ***getPage(pageNumber, callback)***: will get the specified page.
• ***getPageRange(start, stop, callback)***: This will attempt to retrieve all the pages within the range.
• ***getAll(callback)***: will exhaust the entire resource.
• ***setLimit(limit)***: Set the maximum entries per page.
• ***setBulkLimit(limit)***: When calling getAll(), this is the items per page which will be used.

The getPageRange is the only method to access the api inside this library which does not respect the same callback interface. Since it's an asynchronous function it will call the callback whenver it gets back results from a page. The order is rather random and as such it's important to provide an easy-to-use api to find out which page it is.

paginator.getPageRange(1, 5, function(error, data, page) {

});

Tagged Droplet Actions

Droplet actions always have a boolean and callback as it's last two arguments.

API.prototype.rebuildDroplet = function(id, image, tagged, callback)

If the tagged boolean is true, the id argument will be used as a tag instead and the action will be performed against all droplets with the specified tag. In that case, the result will be an array of actions.

The "tagged" argument is optional for the sake of backwards compatibility.

Methods

Refer to the actual API Documentation to learn what the returned values can be. Bear in mind that the returned data is sanitized.

Methods marked with a star (*) are paginated methods.

• Account
  • getUserInfo
• Actions
  • listActions (*)
  • getAction
• Domains
  • listDomains (*)
  • createDomain
  • getDomain
  • deleteDomain
• Domain Records
  • listDomainRecords (*)
  • getDomainRecord
  • createDomainRecord
  • updateDomainRecord
  • deleteDomainRecord
• Droplets
  • listDroplets (*)
  • getDroplet
  • listAvailableKernels (*)
  • listDropletsByTag (*)
  • listDropletSnapshots (*)
  • listDropletBackups (*)
  • listDropletActions (*)
  • createDroplet
  • deleteDroplet
  • deleteDropletsByTag
  • listDropletNeighbors (*)
  • listNeighbors (*)
• Droplet actions
  • enableDropletBackups
  • disableDropletBackups
  • rebootDroplet
  • powerCycleDroplet
  • shutdownDroplet
  • powerOffDroplet
  • powerOnDroplet
  • restoreDroplet
  • passwordResetDroplet
  • resizeDroplet
  • rebuildDroplet
  • renameDroplet
  • changeDropletKernel
  • enableIpv6Droplet
  • enableDropletPrivateNetwork
  • snapshotDroplet
  • getDropletAction
• Images
  • listImages (*)
  • listDistributionImages
  • listApplicationImages
  • listUserImages (*)
  • listImageActions (*)
  • getImage
  • getImageBySlug
  • updateImage
  • deleteImage
• Image Actions
  • transferImage
  • imageToSnapshot
  • getImageAction
• SSH Keys
  • listKeys (*)
  • createKey
  • getKey
  • updateKey
  • destroyKey
• Regions
  • listRegions (*)
• Sizes
  • listSizes (*)
• Floating IPs
  • listFloatingIPs (*)
  • createFloatingIP
  • createUnassignedFloatingIP
  • getFloatingIP
  • deleteFloatingIP
• Floating IP Actions
  • assignFloatingIP
  • unassignFloatingIP
  • listFloatingIPActions (*)
  • getFloatingIPAction
• Tags
  • listTags (*)
  • createTag
  • getTag
  • updateTag
  • tag
  • untag
  • deleteTag

getUserInfo

api.getUserInfo(function(err, info) {

});

listActions*

// Exhaustive call (not recommended here)
api.listActions(function(err, actions) {

});

// Paginator object
var paginator = api.listActions();

getAction

api.getAction(id, function(err, action) {

})

listDroplets*

// Exhaustive call
api.listDroplets(function(err, droplets) {

});

// Paginator object
var paginator = api.listDroplets();

listRegions*

// Exhaustive call (recommended)
api.listRegions(function(err, regions) {

});

// Paginator object
var paginator = api.listRegions();

listSizes*

// Exhaustive call (recommended)
api.listSizes(function(err, sizes) {

});

// Paginator object
var paginator = api.listSizes();

TODO

• Image list functions which filter on type are flawed
• Implement actual request/response testing using a local dummy server and hardcoded JSON responses.

License

MIT