Wrapper library for utilizing DigitalOcean API v2 in Rust

Overview

doapi-rs

Travis GitHub license GitHub release Join the chat at https://gitter.im/kbknapp/doapi-rs

Wrapper library for utilizing DigitalOcean API v2 in Rust

Disclaimer

This library is in alpha - it may do anything up to, and including, eating your laundry.

Example

Full details can be found in the doapi documentation or the DigitalOcean v2 API documentation.

The following example takes a snapshot of an existing droplet, which in turn sends back an Action.

let auth_token = "INSERT AUTH TOKEN HERE";
let domgr = DoManager::with_auth(&auth_token);
let snapshot_name = "my new snapshot";
let droplet_id = "1234567";

print!("Sending request...");
match domgr.droplet(droplet_id)
           .snapshot(snapshot_name)
           .retrieve() {
    Ok(action) => {
        println!("Success!\n\t");
        println!("{}\n", action);
    }
    Err(e) => {
        println!("Failed\n\t.");
        println!("{}\n", e);
    }
}

This library can be used to send the request and retrieve the object back from DigitalOcean all at once (as in the above example), or you use this library to build the request and change it to your liking. For example (still using the above as a base), you could see the request being sent to DigitalOcean without sending it via:

domgr.droplet(droplet_id)
     .snapshot(snapshot_name)
     .to_string();

You can also get the raw JSON back from DigitalOcean

print!("Sending request...")
match domgr.droplet(droplet_id)
           .snapshot(snapshot_name)
           .retrieve_json() {
Ok(json) => {
    println!("Success!\n\t");
    println!("{}\n", json);
},
Err(e) => {
    pritnln!("Failed\n\t.")
    println!("{}\n", e);
}

You can also get the raw hyper requests and responses for your manipulation.

Usage

At the moment, doapi requeires a nightly Rust compiler.

Add doapi as a dependecy in your Cargo.toml file to use from crates.io:

[dependencies]
doapi = "*"

Or track the latest on the master branch at github:

[dependencies.doapi]
git = "https://github.com/kbknapp/doapi-rs.git"

Add extern crate doapi; to your crate root.

DigitalOcean Personal Auth Token

In order to use the DigitalOcean v2 API, you must generate a Personal Authentication Token. This token can then be passed to the DoManager in order to build requests and retrieve results.

Personal Auth Token's can be Read/Write, or Read Only/Write Only. In order to process destructive API calls (such as various .delete(), .create(), .update() etc.) you must have a token with Write priviledges.

To generate a new Personal Auth Token see the following DigitalOcean details

More Information

You can find complete documentation on the github-pages site for this project.

Contributing

Contributions are always welcome! And there is a multitude of ways in which you can help depending on what you like to do, or are good at. Anything from documentation, code cleanup, issue completion, new features, you name it, even filing issues is contributing and greatly appreciated!

NOTE: One of the best ways to help right now is to simply use the library and report issues!

  1. Fork doapi
  2. Clone your fork (git clone https://github.com/$YOUR_USERNAME/doapi-rs && cd doapi-rs)
  3. Create new branch (git checkout -b new-branch)
  4. Make your changes, and commit (git commit -am "your message")
  • I use a conventional changelog format so I can update my changelog using clog
  • Format your commit subject line using the following format: TYPE(COMPONENT): MESSAGE where TYPE is one of the following:
    • feat - A new feature
    • imp - An improvement to an existing feature
    • perf - A performance improvement
    • docs - Changes to documentation only
    • tests - Changes to the testing framework or tests only
    • fix - A bug fix
    • refactor - Code functionality doesn't change, but underlying structure may
    • style - Stylistic changes only, no functionality changes
    • wip - A work in progress commit (Should typically be git rebase'ed away)
    • chore - Catch all or things that have to do with the build system, etc
  • The COMPONENT is optional, and may be a single file, directory, or logical component. Can be omitted if commit applies globally
  1. git rebase into concise commits and remove --fixups (git rebase -i HEAD~NUM where NUM is number of commits back)
  2. Push your changes back to your fork (git push origin $your-branch)
  3. Create a pull request! (You can also create the pull request first, and we'll merge when ready. This a good way to discuss proposed changes.)

Recent Breaking Changes

Although I do my best to keep breaking changes to a minimum, being that this a sub 1.0 library, there are breaking changes from time to time in order to support better features or implementation. For the full details see the changelog.md

NONE Yay :)

Deprecations

Old method names will be left around for some time.

NONE Yay :)

Comments
  • Make more fields public

    Make more fields public

    This PR makes all fields in responses public - there's not much point in having them if they can't be used!

    On the other hand, I was considering making a PR to convert a bunch of things to better types (e.g. f64 id to u64), which would be less of a breaking change (slightly) if these fields stayed private for now.

    Thoughts @kbknapp ?

    opened by aidanhs 5
  • Fix lints

    Fix lints

    In https://github.com/kbknapp/doapi-rs/commit/0c223c671233024c6e38a7b99d20f6d324d14ca1, you added new #![deny(..)] lints, without changing the code accordingly. As a result, doapi-rs fails to build because of missing copy and debug implementations, missing docs and "unnecessary qualifications" that are actually useful โ€” that is, the code fails to compile without them.

    This PR removes the three problematic lints, fixes a warning (the append feature is now stable) and runs rustfmt (I couldn't easily do it in a separate commit as I have rust.vim configured to run it automatically on save).

    opened by yberreby 5
  • Permit an absent content-type

    Permit an absent content-type

    Despite what the DO docs say for deleting a droplet (https://developers.digitalocean.com/documentation/v2/#delete-a-droplet), it does not appear to return with any content type (which is valid).

    I think the better way to handle this would be to make content-type an Option and bump the version of doapi-rs due to the backwards incompatibility - let me know if you're ok with this and I'll alter this PR.

    opened by aidanhs 4
  • Allow droplet ID retrieval

    Allow droplet ID retrieval

    I am trying to create a droplet, and retrieve its ID.

    manager.droplets().create(&settings).retrieve().unwrap()
    

    This returns a doapi::response::Droplet, which contains the droplet ID. Unfortunately, this struct's fields are all private, and it exposes no way to access the ID, nor any other field. Would you consider making these fields public, or adding accessors for them?

    As a side note, why are all numeric fields (id, memory, vcpus) of type f64? I suspect fractional CPUs and IDs are a rarity :)

    opened by yberreby 4
  • snapshot_id and backup_id are numeric

    snapshot_id and backup_id are numeric

    As shown in the docs (https://developers.digitalocean.com/documentation/v2/#retrieve-an-existing-droplet-by-id) and the DO golang api (provided by DO) https://github.com/digitalocean/godo/blob/3bd6277a85c14f0e421bf3c50da4c4d9dcb7ebfa/droplets.go#L50

    opened by aidanhs 3
  • Add a Gitter chat badge to README.md

    Add a Gitter chat badge to README.md

    kbknapp/doapi-rs now has a Chat Room on Gitter

    @kbknapp has just created a chat room. You can visit it here: https://gitter.im/kbknapp/doapi-rs.

    This pull-request adds this badge to your README.md:

    Gitter

    If my aim is a little off, please let me know.

    Happy chatting.

    PS: Click here if you would prefer not to receive automatic pull-requests from Gitter in future.

    opened by gitter-badger 1
  • Update to rust 2018 edition

    Update to rust 2018 edition

    I've done a significant rewrite to update doapi-rs to the Rust 2018 edition.

    Brief summary of the changes:

    1. Replace hyper with reqwest. This necessitated hosting a Client object in the domgr to allow connection pooling.
    2. Added ability to override the base url to allow testing and created some tests.
    3. RequestBuilder objection are now generated by domgr to permit use of Client object and sharing auth token.

    More work is definitely required but it does compile and I'd like to get your feedback.

    opened by cullenvandora 0
  • Implement Images API

    Implement Images API

    • [x] response struct
    • [x] list all
    • [x] list distro images
    • [x] list application images
    • [x] list user images
    • [x] list available images
    • [x] retrieve by id
    • [x] retrieve by slug
    • [x] list actions for image id
    • [x] update
    • [x] delete
    Upstream API 
    opened by kbknapp 0
  • Implement Droplet Actions API

    Implement Droplet Actions API

    • [x] response struct
    • [x] disable backups
    • [x] reboot
    • [x] power cycle
    • [x] shutdown
    • [x] power off
    • [x] power on
    • [x] restore
    • [x] reset password
    • [x] resize
    • [x] rebuild
    • [x] rename
    • [x] change kernel
    • [x] enable IPv6
    • [x] enable private networking
    • [x] snapshot
    • [x] upgrade
    • [x] retrieve action by id
    Upstream API 
    opened by kbknapp 0
  • Implement Droplets API

    Implement Droplets API

    Droplet

    • [x] response struct
    • [x] request struct
    • [x] create
    • [x] retrieve single by id
    • [x] list all
    • [x] list all kernels for id
    • [x] list all snapshots for id
    • [x] list all backups for id
    • [x] list all actions for id
    • [x] delete
    • [x] list neighbors for id
    • [x] list all neighbors
    • [x] list upgrades

    kernel

    • [x] response struct

    Network

    • [ ] response struct

    Backup

    • [x] response struct

    Snapshot

    • [x] response struct

    Image

    • [x] response struct

    Size

    • [x] response struct

    Region

    • [x] response struct

    Upgrades

    • [x] response struct
    Upstream API 
    opened by kbknapp 0
  • next_backup_window is just start and end times

    next_backup_window is just start and end times

    https://github.com/kbknapp/doapi-rs/blob/2cdf3515aa5980843bd65dac154984c025802668/src/response/droplet.rs#L69

    it shouldn't be a Backup struct, it actually looks like

                "next_backup_window": {
                    "end": "2016-12-14T19:00:00Z",
                    "start": "2016-12-13T20:00:00Z"
                },
    

    (not got a chance to fix at the moment)

    opened by aidanhs 0
  • Error on retrieving droplets

    Error on retrieving droplets

    let auth_token = "my token";
     let domgr = DoManager::with_token(&auth_token);
     match domgr.droplets().retrieve() {
                      Ok(val) => "OK".to_string(),
                      Err(t) => t.to_string(),
                  });
    

    Returns error:

    Error "expected value" at line 0 column 0
    

    Likely due to upstream API change

    bug 
    opened by kbknapp 2
Releases(v0.1.1)
Owner
Kevin K.
I love to code, skydive, and do the things.
Kevin K.
A rust wrapper for the spam protection API

SpamProtection-rs Table of contents About Supported Rust version Features How to use Credits License About This repo has been shifted to the official

cyberknight777 28 Aug 5, 2022
A Rust wrapper for the SponsorBlock API.

sponsor-block A Rust wrapper for the SponsorBlock API, which you can find complete documentation for here. Uses SponsorBlock data licensed under CC BY

Zacchary Dempsey-Plante 8 Nov 19, 2022
Autogenerated wrapper for the Telegram Bot API written in Rust.

An Elegant Rust Client for Telegram Bot API crates.io โ€ข docs.rs Table of contents Introduction Key Features Installation Getting Started Documentation

FerrisGram 22 Oct 29, 2022
A simple, fast and fully-typed JSPaste API wrapper for Rust

rspaste A simple, fast and fully-typed JSPaste API wrapper for Rust. aidak.tk ยป Installation Put the desired version of the crate into the dependencie

Aidak 2 May 17, 2022
A simple, yet feature-filled wrapper around the coqui-stt C API

A simple, yet feature-filled wrapper around the coqui-stt C API

0/0 56 Jan 3, 2023
A safe wrapper around Gamercade's raw Api.

gamercade-rs A safe wrapper around Gamercade's Raw Api. As the Raw Api requires using a lot of unsafe and hiding of values through different types (fo

null 1 Aug 23, 2022
A minimal discord api wrapper.

descord Descord is a discord api wrapper. Example use descord::prelude::*; #[tokio::main] async fn main() { let mut client = Client::new(

null 12 May 6, 2024
Modrinth API is a simple library for using, you guessed it, the Modrinth API in Rust projects

Modrinth API is a simple library for using, you guessed it, the Modrinth API in Rust projects. It uses reqwest as its HTTP(S) client and deserialises responses to typed structs using serde.

null 21 Jan 1, 2023
A repository full of manually generated hand curated JSON files, which contain the API Types that the Discord API returns.

Discord API Types A repository full of manually generated hand curated JSON files, which contain the API Types that the Discord API returns. Also did

Unofficial Discord Documentation 1 Sep 16, 2022
dm-jitaux is a Rust-based JIT compiler using modified auxtools, dmasm and Inkwell LLVM wrapper for boosting Byond DM performance without any hassle!

dm-jitaux is a Rust-based JIT compiler using modified auxtools, dmasm and Inkwell LLVM wrapper for boosting Byond DM performance without any hassle (such as rewriting/refactroing your DM code).

SS220 20 Dec 13, 2022
FFI wrapper around cfitsio in Rust

rust-fitsio FFI wrapper around cfitsio in Rust Installation fitsio supports versions of cfitsio >= 3.08. cfitsio must be compiled with reentrant suppo

Simon Walker 22 Dec 24, 2022
Thin wrapper around starship.rs to format kakoune status line

kakship is just a thin wrapper around starship to format the status line of kakoune and is meant to be used with the included kakoune script kakship.kak.

Eric Burghard 15 Jun 7, 2022
A lightweight Discord wrapper made in Tauri

Discord-Tauri is a work in progress lightweight wrapper for Discord.

null 104 Dec 20, 2022
cargo-check This is a wrapper around cargo rustc

cargo-check This is a wrapper around cargo rustc -- -Zno-trans. It can be helpful for running a faster compile if you only need correctness checks. In

Ray Solomon 99 Oct 13, 2022
Provides a wrapper to deserialize clap app using serde.

clap-serde Provides a wrapper to deserialize clap app using serde. API Reference toml const CLAP_TOML: &'static str = r#" name = "app_clap_serde" vers

null 17 Jan 9, 2023
๐ŸŒ‹ A very lightweight wrapper around the Vulkan Memory Allocator ๐Ÿฆ€

?? vk-mem-alloc-rs A very lightweight wrapper around the Vulkan Memory Allocator ?? [dependencies] vk-mem-alloc = "0.1.1" Simple Vulkan Memory Allocat

Project KML 13 Nov 8, 2022
Notion Offical API client library for rust

Notion API client library for rust.

Jake Swenson 65 Dec 26, 2022
An asynchronous Rust client library for the Hashicorp Vault API

vaultrs An asynchronous Rust client library for the Hashicorp Vault API The following features are currently supported: Auth AppRole JWT/OIDC Token Us

Joshua Gilman 59 Dec 29, 2022
Serenity is a Rust library for the Discord API

serenity Serenity is a Rust library for the Discord API. View the examples on how to make and structure a bot. Serenity supports bot login via the use

serenity 3.3k Jan 2, 2023