README.md

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)