blom / barge

Ruby library for version 2 of DigitalOcean's API

Barge

Ruby library for version 2 of DigitalOcean's API.

Installation

gem install barge

Ruby 1.9.3 and up is required. See the .travis.yml file for a list of supported rubies.

Initialize

barge = Barge::Client.new(access_token: 'token')

or

barge = Barge::Client.new do |config|
  config.access_token = 'token'
end

Resources

General

Hashie::Mash

Hashie::Mash is used so that attributes can be accessed using dot notation:

droplet = barge.droplet.show(droplet_id)
droplet.droplet.name       # => "foo"
droplet.droplet.image.id   # => 123
droplet.droplet.size!.slug # => "512mb"

Notice that size! and not size was used. This is because size already is a method, and Hashie::Mash will not override it. You can also use square brackets:

droplet[:droplet][:size][:slug]    # => "512mb"
droplet['droplet']['size']['slug'] # => "512mb"

See the API documentation on responses if you are wondering why attributes are contained within a droplet key.

#success?

You can use #success? to check if a successful HTTP status code was returned:

barge.droplet.create(options).success? # => true

#response

Barge uses Faraday. You can use #response to get to the response object:

barge.droplet.show(droplet_id).response # => Faraday::Response

Pagination

For paginated resources, a maximum of 200 objects are returned by default (the maximum allowed by the API).

Limit objects per page and/or get a specific page

barge.image.all(per_page: 10, page: 2)

Check if a response is paginated

barge.action.all.paginated? # => true
barge.region.all.paginated? # => false

Get the previous page number

barge.image.all(per_page: 5, page: 2).prev_page # => 1

Get the next page number

barge.image.all(per_page: 5, page: 2).next_page # => 3

Get the last page number

barge.image.all(per_page: 5, page: 2).last_page # => 8

Account

Show account information

barge.account.show

Action

Show all actions

barge.action.all

Show action

barge.action.show(action_id)

Droplet

Create droplet

barge.droplet.create(options)

See the API documentation for options.

Show all droplets

barge.droplet.all

Show droplet

barge.droplet.show(droplet_id)

Show droplet backups

barge.droplet.backups(droplet_id)

Show droplet kernels

barge.droplet.kernels(droplet_id)

Show droplet snapshots

barge.droplet.snapshots(droplet_id)

Create snapshot

barge.droplet.snapshot(droplet_id, name: 'image name')

Destroy droplet

barge.droplet.destroy(droplet_id)

Rename droplet

barge.droplet.rename(droplet_id, name: 'new name')

Reboot droplet

barge.droplet.reboot(droplet_id)

Shutdown droplet

barge.droplet.shutdown(droplet_id)

Power off droplet

barge.droplet.power_off(droplet_id)

Power cycle droplet

barge.droplet.power_cycle(droplet_id)

Power on droplet

barge.droplet.power_on(droplet_id)

Resize droplet

barge.droplet.resize(droplet_id, size: 'size slug')

Where size slug is for example 1024mb.

Rebuild droplet

barge.droplet.rebuild(droplet_id, image: image_id)

Restore droplet

barge.droplet.restore(droplet_id, image: image_id)

Reset a droplet's password

barge.droplet.password_reset(droplet_id)

Change a droplet's kernel

barge.droplet.change_kernel(droplet_id, kernel: kernel_id)

Enable IPv6 for a droplet

barge.droplet.enable_ipv6(droplet_id)

Disable backups for a droplet

barge.droplet.disable_backups(droplet_id)

Enable private networking for a droplet

barge.droplet.enable_private_networking(droplet_id)

Show droplet actions

barge.droplet.actions(droplet_id)

Show droplet action

barge.droplet.show_action(droplet_id, action_id)

Image

Show all images

barge.image.all
barge.image.all(private: true)
barge.image.all(type: :application)
barge.image.all(type: :distribution)

Show image

By ID:

barge.image.show(image_id)

By image slug (public images):

barge.image.show('image slug')

Where image slug is for example ubuntu-13-10-x64.

Update image

barge.image.update(image_id, options)

See the API documentation for options.

Destroy image

barge.image.destroy(image_id)

Transfer image

barge.image.transfer(image_id, region: 'region slug')

Where region slug is for example sfo1.

Show image action

barge.image.show_action(image_id, action_id)

Domain

Create domain

barge.domain.create(options)

See the API documentation for options.

Show all domains

barge.domain.all

Show domain

barge.domain.show(domain_name)

Destroy domain

barge.domain.destroy(domain_name)

Create domain record

barge.domain.create_record(domain_name, options)

See the API documentation for options.

Show all domain records

barge.domain.records

Show domain record

barge.domain.show_record(domain_name, record_id)

Update domain record

barge.domain.update_record(domain_name, record_id, options)

Destroy domain record

barge.domain.destroy_record(domain_name, record_id)

Key

Create key

barge.key.create(options)

See the API documentation for options.

Show all keys

barge.key.all

Show key

barge.key.show(key_id_or_fingerprint)

Update key

barge.key.update(key_id_or_fingerprint, options)

See the API documentation for options.

Destroy key

barge.key.destroy(key_id)

Region

Show all regions

barge.region.all

Size

Show all sizes

barge.size.all

Floating IP

Show all floating IPs

barge.floating_ip.all

Create floating IP

barge.floating_ip.create(droplet_id: droplet_id)
barge.floating_ip.create(region: region)

Show floating IP

barge.floating_ip.show(ip_address)

Destroy floating IP

barge.floating_ip.destroy(ip_address)

Assign a floating IP to a droplet

barge.floating_ip.assign(ip_address, droplet_id: droplet_id)

Unassign a floating IP

barge.floating_ip.unassign(ip_address)

barge's Issues

There was a SyntaxError while loading barge.gemspec:

Best way to wait for a server to finish creating?

Hey,

What would you recommend is the best way to wait for a server to finish creating? In the Fog library (https://github.com/fog/fog) there is a method on the server object of wait_for. Is there a similar thing here, or is it just a case of polling the actions api manually?

Thanks
Scott

Show Private Images

Currently there's no way to get users private images:

https://developers.digitalocean.com/documentation/v2/#list-a-user-s-images

Example Call:

curl -X GET -H 'Content-Type: application/json' -H 'Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582' "https://api.digitalocean.com/v2/images?page=1&per_page=1&private=true"

Add CLI flow to get OAuth Token

Since v2 uses OAuth, it would be nice to have a basic CLI to generate an OAuth token.

The dropbox-api has a good example:

https://github.com/futuresimple/dropbox-api#web-based-authorization
https://github.com/futuresimple/dropbox-api/blob/master/lib/dropbox-api/tasks.rb

Changing Faraday options

How do we change Faraday options?

I basically want to be able to do:

faraday.response :logger

Failed to install barge 0.10.0

uninitialized constant DOCL::CLI::Barge (NameError) (using docl 0.0.4)

http://imgur.com/xNWg0ob
http://imgur.com/I4VOH8b

Rubocop Matrix issues

Robocop needs to be locked down to 0.23 so it works with 1.9.2

OR

We just remove 1.9.2 as it's EOL anyways 👍

Gem::InstallError: rubocop requires Ruby version >= 1.9.3.
Gem::RemoteFetcher::FetchError: Errno::ETIMEDOUT: Connection timed out - connect(2) (https://rubygems.org/gems/multipart-post-2.0.0.gem)
An error occurred while installing rubocop (0.26.0), and Bundler cannot
continue.
Make sure that `gem install rubocop -v '0.26.0'` succeeds before bundling.

API 2.0 Breaking Change:

Breaking changes in Action objects (March 20, 2015)

Date: February 20, 2015 Tagged In: API v2 Author Phillip Baker
All action objects, i.e. those returned by the /v2/actions, /v2/droplets/$ID/actions and /v2/images/$ID/actions endpoint now return a region_slug attribute, in addition to a region attribute. At 00:01 March 20, 2015 UTC, API v2 will start returning an embedded region object at the region attribute, not a slug.

https://developers.digitalocean.com/documentation/changelog/api-v2/actions-breaking-changes-upgrade-path/

Add Snapshot listing

Add ability to list and remove snapshots

https://developers.digitalocean.com/documentation/v2/#snapshots

Add Block Storage

New Block Storage API:

https://developers.digitalocean.com/documentation/v2/#block-storage