DigitalOcean

A crate for interacting with the Digital Ocean API.

While browsing this documentation, please feel encouraged to reference the DigitalOcean docs.

A Basic Example

extern crate digitalocean;
use digitalocean::prelude::*;
use std::env;

fn main() {
    let api_key = env::var("API_KEY")
        .expect("API_KEY not set.");
    let client = DigitalOcean::new(api_key)
        .unwrap();

    Droplet::list()
        .execute(&client);
}

Usage Fundamentals

All values (Domain, SshKey, etc) can be found in the api module.

Calling an action will return a Request<_,_> type. For example Droplet::create() will create a Request<Create, Droplet>. These types may then have specific futher functions to futher build up the request or transform it into some other request.

extern crate digitalocean;
use digitalocean::DigitalOcean;
use digitalocean::api::Domain;

fn main() {
    // Gets details of a specific domain.
    let req = Domain::get("foo.com");

    // Get the records for that domain instead (futher build the request)
    let req = req.records();
    // Get the records of a domain without having a prior request.
    let req = Domain::get("foo.com").records();

    // Create a new record for a domain
    let req = Domain::get("foo.com").records().create("CNAME", "test", "127.0.0.1");
}

In order to realize any action, .execute() must be called with a DigitalOcean client. It is also possible to call do_client.execute(some_request).

In order to use the entire API, it is recommended to reference the various Request types.

Design

The crate is founded on a few design considerations:

Keep things simple and generic.
Map closely to the DigitalOcean API.
Requests are agnostic over Clients.
It should be difficult to make an invalid API request.
Use static dispatch as much as possible.
Only the bare minimum amount of information should be carried around.
Allow for easy construction of separate clients (hyper, etc.)
No caching (yet). (DigitalOcean does not have ETags)

Debugging

This crate uses the log crate. You can see digitalocean logs by passing an environment variable such as:

RUST_LOG=digitalocean=debug cargo run

Development Status

This crate is in a prototype state.

Not all endpoints have been fully end-to-end tested on the production DigitalOcean API. It's very likely that some endpoints will have parsing errors due to unexpected values returned from the API.

If something does not work please file a bug!

Feedback, patches, and new features are encouraged. Please just open an issue or PR!

Hoverbear / digitalocean

readme