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!
- Fork
doapi - Clone your fork (
git clone https://github.com/$YOUR_USERNAME/doapi-rs && cd doapi-rs) - Create new branch (
git checkout -b new-branch) - 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): MESSAGEwhereTYPEis one of the following:feat- A new featureimp- An improvement to an existing featureperf- A performance improvementdocs- Changes to documentation onlytests- Changes to the testing framework or tests onlyfix- A bug fixrefactor- Code functionality doesn't change, but underlying structure maystyle- Stylistic changes only, no functionality changeswip- A work in progress commit (Should typically begit rebase'ed away)chore- Catch all or things that have to do with the build system, etc
- The
COMPONENTis optional, and may be a single file, directory, or logical component. Can be omitted if commit applies globally
git rebaseinto concise commits and remove--fixups (git rebase -i HEAD~NUMwhereNUMis number of commits back)- Push your changes back to your fork (
git push origin $your-branch) - 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 :)
28 Aug 5, 2022
8 Nov 19, 2022
22 Oct 29, 2022
2 May 17, 2022
56 Jan 3, 2023
1 Aug 23, 2022
12 May 6, 2024
21 Jan 1, 2023
1 Sep 16, 2022
20 Dec 13, 2022
22 Dec 24, 2022
15 Jun 7, 2022
104 Dec 20, 2022
99 Oct 13, 2022
17 Jan 9, 2023
13 Nov 8, 2022
65 Dec 26, 2022
59 Dec 29, 2022
3.3k Jan 2, 2023