DigOc

An Elixir client for the Digital Ocean API. If you find errors, please don't hesitate to file a GitHub issue.

DigOc API Documentation is available at http://hexdocs.pm/digoc

The Digital Ocean API documenation will prove helpful.

[Please note: the "examples" documentation effort here is ongoing but I believe the API is fully documented. If something there is confusing or missing or just plain wrong it's a bug; please file a GitHub issue.]

Porcelain vs. Plumbing

I'm working on a separate library that wraps this library with more developer friendly functions. That is a work in progress and in no way deprecates this code (quite the opposite: it relies on it). If you're doing anything more than a quick 'n' dirty script, it might be worth taking a look.

Authentication

Generate a Digital Ocean from the Applications & API page. Set the environment variable DIGOC_API2_TOKEN to the value of the token.

This value is available programmatically:

iex> DigOc.api_token
"12345...7890"

Results

All of the commands have two varients, e.g., DigOc.account/0 and DigOc.account!/0. The first returns a three-tuple:

iex> DigOc.account
{:ok,
 %{account: %{droplet_limit: 25, email: "[email protected]",
     email_verified: true, uuid: "12345"}},
 %{"CF-RAY" => "1a6a3abe45cf115f-DFW",
   "Content-Type" => "application/json; charset=utf-8",
   "RateLimit-Limit" => "1200",
   "RateLimit-Remaining" => "1199",
   "RateLimit-Reset" => "1420910715",
   "Server" => "cloudflare-nginx",
   "Status" => "200 OK"}}`

The latter just the response body:

iex> DigOc.account!
%{account: %{droplet_limit: 25, email: "[email protected]",
email_verified: true, uuid: "12345"}}

The response body is the original JSON decoded by Poison. I've given some thought to making these actual records but don't see that there's a real benefit to that (in fact, that just opens the door to more maintenance when the API changes). If you think otherwise, please let me know.

Examples

NB: The results shown have been edited and often truncated. For documentation on the datastructures that are being returned, please consult the D.O. API v2 documentation.

Account

iex(8)> DigOc.account!
%{account: %{droplet_limit: 25, email: "[email protected]",
    email_verified: true, uuid: "12345"}}

Actions and Pagination

iex(10)> res = DigOc.actions!(3)
%{actions: [%{completed_at: "2015-01-10T16:07:39Z", id: 40940233,
     region: "nyc3", resource_id: 3723327, resource_type: "droplet",
     started_at: "2015-01-10T16:07:36Z", status: "completed",
     type: "destroy"},
   %{completed_at: "2015-01-09T20:31:21Z", id: 40885160, region: "nyc3",
     resource_id: 3723351, resource_type: "droplet",
     started_at: "2015-01-09T20:31:16Z", status: "completed",
     type: "destroy"},
   %{completed_at: "2015-01-09T20:31:15Z", id: 40885158, region: "nyc3",
     resource_id: 3723351, resource_type: "droplet",
     started_at: "2015-01-09T20:31:15Z", status: "completed",
     type: "rename"}],
 links: %{pages:
     %{last: "https://api.digitalocean.com/v2/actions?page=382&per_page=3",
       next: "https://api.digitalocean.com/v2/actions?page=2&per_page=3"}},
 meta: %{total: 1144}}
       
iex(12)> DigOc.Page.next?(res)
true
iex(13)> DigOc.Page.last?(res)
true
iex(14)> DigOc.Page.prev?(res)
false

iex(16)> last_res = DigOc.Page.last!(res)
%{actions: [%{completed_at: "2012-09-20T17:59:05Z", id: 137720,
              region: "nyc1", resource_id: 25817, resource_type: "droplet",
              started_at: "2012-09-20T17:58:05Z", status: "completed",
              type: "create"}],
  links: %{pages:
   %{first: "https://api.digitalocean.com/v2/actions?page=1&per_page=3",
     prev: "https://api.digitalocean.com/v2/actions?page=381&per_page=3"}},
  meta: %{total: 1144}}

iex(18)> DigOc.Page.next!(last_res)
** (RuntimeError) No bookmark for next page.
    (digoc) lib/digoc/page.ex:24: DigOc.Page.get_page/2
    (digoc) lib/digoc/page.ex:13: DigOc.Page.next!/1


iex(18)> DigOc.action!(40940233)
%{action: %{completed_at: "2015-01-10T16:07:39Z", id: 40940233,
    region: "nyc3", resource_id: 3723327, resource_type: "droplet",
    started_at: "2015-01-10T16:07:36Z", status: "completed",
    type: "destroy"}}

Domains

iex(26)>  DigOc.Domain.new!("bapi.us", "10.0.0.1")
%{domain: %{name: "bapi.us", ttl: 1800, zone_file: nil}}

iex(29)>  DigOc.Domain.new!("another.bapi.us", "10.0.0.1")
%{domain: %{name: "another.bapi.us", ttl: 1800, zone_file: nil}}

iex(30)> DigOc.domains!
%{domains: [%{name: "bapi.us", ttl: 1800,
     zone_file: "$ORIGIN bapi.us.\n..."},
   %{name: "another.bapi.us", ttl: 1800,
     zone_file: "$ORIGIN another.bapi.us.\n..."}],
  links: %{}, meta: %{total: 2}}

iex(32)> DigOc.domain!("another.bapi.us")
%{domain: %{name: "another.bapi.us", ttl: 1800,
    zone_file: "$ORIGIN another.bapi.us.\n..."}}

ex(2)> DigOc.Domain.delete("another.bapi.us")
{:ok, "", %{"Status" => "204 No Content"}}

Domain Records

iex(3)>  DigOc.Domain.Record.new!("bapi.us", %{ type: "A",
                                                name: "test.bapi.us",
                                                data: "10.0.0.2" })
%{domain_record: %{data: "10.0.0.2", id: 3833327, name: "test.bapi.us",
port: nil, priority: nil, type: "A", weight: nil}}

iex(4)> DigOc.Domain.records!("bapi.us")
%{domain_records: [%{data: "ns1.digitalocean.com", id: 3833164, name: "@",
     port: nil, priority: nil, type: "NS", weight: nil},
   %{data: "ns2.digitalocean.com", id: 3833165, name: "@", port: nil,
     priority: nil, type: "NS", weight: nil},
   %{data: "ns3.digitalocean.com", id: 3833166, name: "@", port: nil,
     priority: nil, type: "NS", weight: nil},
   %{data: "10.0.0.1", id: 3833167, name: "@", port: nil, priority: nil,
     type: "A", weight: nil},
   %{data: "10.0.0.2", id: 3833326, name: "test.bapi.us", port: nil,
     priority: nil, type: "A", weight: nil},
   %{data: "10.0.0.2", id: 3833327, name: "test.bapi.us", port: nil,
     priority: nil, type: "A", weight: nil}], links: %{}, meta: %{total: 6}}

iex(9)> DigOc.Domain.record!("bapi.us", 3833327)
%{domain_record: %{data: "10.0.0.2", id: 3833327, name: "test.bapi.us",
port: nil, priority: nil, type: "A", weight: nil}}

iex(2)> DigOc.Domain.Record.update!("bapi.us", 3833327, "prod.bapi.us")
%{domain_record: %{data: "10.0.0.2", id: 3833327, name: "prod.bapi.us",
    port: nil, priority: nil, type: "A", weight: nil}}

iex(3)> DigOc.Domain.Record.delete("bapi.us", 3833327)
{:ok, "", %{"Status" => "204 No Content"}}

Copyright

This library is (c) 2015 BAPI Consulting and released under the MIT License.