v2.16 released and tagged on Sep 03, 2018
Simple & Lightweight API client library for Enterprise Application or Utilities Integration around DigitalOcean RESTful APIs. You can use this library with project based (JVM hosted languages) on Java, Groovy, Scala, Clojure, etc.
Give your support by clicking Hearts on DigitalOcean Developers Community :)
Getting Started
For handy use, DigitalOcean API Client library project dependency definition provided below or you wanna jar Download it from Maven central repo.
Note: master branch maps to v2 APIs and digitalocean turned off v1 APIs as on Nov 9, 2015 .
Maven dependency
<dependency>
<groupId>com.myjeeva.digitalocean</groupId>
<artifactId>digitalocean-api-client</artifactId>
<version>2.16</version>
</dependency>
Gradle/Grails dependency
compile 'com.myjeeva.digitalocean:digitalocean-api-client:2.16'
Groovy Grape
@Grapes(
@Grab(group='com.myjeeva.digitalocean', module='digitalocean-api-client', version='2.16')
)
Scala SBT
libraryDependencies += "com.myjeeva.digitalocean" % "digitalocean-api-client" % "2.16"
Note: For Android projects, kindly include the httpclient-android
library explicitly in your project dependencies.
Getting Help
For API documentation see:
For Example usage see:
- Have a look at DigitalOceanIntegrationTest
Samples
Creating a DigitalOcean Client in three simple ways!
// Way one, just pass on authToken
DigitalOcean apiClient = new DigitalOceanClient(authToken);
// Way two, pass on version number & authToken
DigitalOcean apiClient = new DigitalOceanClient("v2", authToken);
// Way three, pass on version number, authToken & httpClient
// Go ahead and customize httpClient attributes for requirements
CloseableHttpClient httpClient = HttpClients.createDefault();
DigitalOcean apiClient = new DigitalOceanClient("v2", authToken, httpClient);
Let's invoke the method(s) as per need via apiClient
// Fetching all the available droplets from control panel
Droplets droplets = apiClient.getAvailableDroplets(pageNo, perPage);
// Fetching all the available kernels for droplet
Kernels kernels = apiClient.getAvailableKernels(dropletId, pageNo, perPage);
// Create a new droplet
Droplet newDroplet = new Droplet();
newDroplet.setName("api-client-test-host");
newDroplet.setSize(new Size("512mb")); // setting size by slug value
newDroplet.setRegion(new Region("sgp1")); // setting region by slug value; sgp1 => Singapore 1 Data center
newDroplet.setImage(new Image(1601)); // setting by Image Id 1601 => centos-5-8-x64 also available in image slug value
newDroplet.setEnableBackup(Boolean.TRUE);
newDroplet.setEnableIpv6(Boolean.TRUE);
newDroplet.setEnablePrivateNetworking(Boolean.TRUE);
// Adding SSH key info
List<Key> keys = new ArrayList<Key>();
keys.add(new Key(6536653));
keys.add(new Key(6536654));
newDroplet.setKeys(keys);
// Adding Metadata API - User Data
newDroplet.setUserData(" < YAML Content > "); // Follow DigitalOcean documentation to prepare user_data value
Droplet droplet = apiClient.createDroplet(newDroplet);
// Creating multiple droplets
Droplet droplet = new Droplet();
droplet.setNames(Arrays.asList("sub-01.example.com", "sub-02.example.com"));
droplet.setSize("512mb");
droplet.setImage(new Image("ubuntu-14-04-x64"));
droplet.setRegion(new Region("nyc1"));
Droplets droplets = apiClient.createDroplets(droplet);
// Fetch droplet information
Droplet droplet = apiClient.getDropletInfo(dropletId);
// Fetch Available Plans/Sizes supported by DigitalOcean
Sizes sizes = apiClient.getAvailableSizes(pageNo);
// Fetch Available Regions supported by DigitalOcean
Regions regions = apiClient.getAvailableRegions(pageNo);
Accessing RateLimit
header values from return object. This is applicable for all requests.
Droplets droplets = getAvailableDroplets(1, 20);
RateLimit rateLimit = droplets.getRateLimit();
Actions actions = getAvailableActions(2, 40);
RateLimit rateLimit = actions.getRateLimit();
Domain domain = getDomainInfo("myjeeva.com");
RateLimit rateLimit = domain.getRateLimit();
Droplet droplet = getDropletInfo(10000001);
RateLimit rateLimit = droplet.getRateLimit();
Reporting Issues
DigitalOcean API Client uses GitHub’s integrated issue tracking system to record bugs and feature requests. If you want to raise an issue, please follow the recommendations bellow:
- Before you log a bug, please search the issue tracker to see if someone has already reported the problem. If the issue doesn’t already exist, create a new issue.
- Please provide as much information as possible with the issue report, we like to know the version of DigitalOcean API Client that you are using.
- If you need to paste code, or include a stack trace use Markdown ``` escapes before and after your text.
Supported API's and Revision Logs
- Released in v2.16
- Added new endpoint support
/v2/firewalls/*
#83, PR #85, PR #87 (@andreybleme)- Firewalls
Firewalls getAvailableFirewalls(Integer pageNo, Integer perPage) Firewall getFirewallInfo(String firewallId) Firewall createFirewall(Firewall firewall) Firewall updateFirewall(Firewall firewall) Delete deleteFirewall(String firewallId)
- Firewalls
- Links and Meta information made available on POJO #84 @jeevatkm
- Added method
getAvailableDropletsByTagName
#86 #jeevatkm
- Added new endpoint support
- Released in v2.15
- Released in v2.14
- Released in v2.13
- Released in v2.12
- Added monitoring attribute to Create droplet #70 @jeevatkm
- Bug fix: Not able to get Image (Snapshot) Size #68 @jeevatkm
- Added new endpoint support
/v2/certificates/*
#71 @jeevatkm- Certificates
Certificates getAvailableCertificates(Integer pageNo, Integer perPage) Certificate createCertificate(Certificate certificate) Certificate getCertificateInfo(String certificateId) Delete deleteCertificate(String certificateId)
- Certificates
- Released in v2.11
- Added new endpoint support
/v2/load_balancers/*
PR #66 @tlehoux- Load Balancers
LoadBalancers getAvailableLoadBalancers(Integer pageNo, Integer perPage) LoadBalancer createLoadBalancer(LoadBalancer loadBalancer) LoadBalancer getLoadBalancerInfo(String loadBalancerId) LoadBalancer updateLoadBalancer(LoadBalancer loadBalancer) Delete deleteLoadBalancer(String loadBalancerId) Response addDropletsToLoadBalancer(String loadBalancerId, List dropletIds) Delete removeDropletsFromLoadBalancer(String loadBalancerId, List dropletIds) Response addForwardingRulesToLoadBalancer(String loadBalancerId, List forwardingRules) Delete removeForwardingRulesFromLoadBalancer(String loadBalancerId, List forwardingRules)
- Load Balancers
- Added new endpoint support
- Released in v2.10
- Removed unsupported API
/v2/tags/$TAG_NAME
refer DO changelog
- Removed unsupported API
- Released in v2.9
- Added new API support delete droplet by tag name #61
- Droplet
Delete deleteDropletByTagName(String tagName)
- Droplet
- Added new API support delete droplet by tag name #61
- Released in v2.8
- Added new endpoint support
/v2/snapshots/*
#58, PR #57 (@samuelfac)- Snapshots
Snapshots getAvailableSnapshots(Integer pageNo, Integer perPage) Snapshots getAllDropletSnapshots(Integer pageNo, Integer perPage) Snapshots getAllVolumeSnapshots(Integer pageNo, Integer perPage) Snapshot getSnaphotInfo(String snapshotId) Delete deleteSnapshot(String snapshotId)
- Due to new endpoint
/v2/snapshots/*
introduced by DO, I had to refactor following methods to make it clean and meaningfulgetAvailableSnapshots(Integer dropletId, Integer pageNo, Integer perPage) ==> getDropletSnapshots(Integer dropletId, Integer pageNo, Integer perPage) getAvailableKernels(Integer dropletId, Integer pageNo, Integer perPage) ==> getDropletKernels(Integer dropletId, Integer pageNo, Integer perPage) getAvailableBackups(Integer dropletId, Integer pageNo) ==> getDropletBackups(Integer dropletId, Integer pageNo, Integer perPage)
- Snapshots
- Added
volumes
andtags
attribute for create droplet #56
- Added new endpoint support
- Released in v2.7
- Added new endpoint support
/v2/volumes/*
#54, PR #55 (@strokine)- Volumes
Volumes getAvailableVolumes(String regionSlug) Volume createVolume(Volume volume) Volume getVolumeInfo(String volumeId) Volumes getVolumeInfo(String volumeName, String regionSlug) Delete deleteVolume(String volumeId) Delete deleteVolume(String volumeName, String regionSlug)
- Volumes Actions
Action attachVolume(Integer dropletId, String volumeId, String regionSlug) Action attachVolumeByName(Integer dropletId, String volumeName, String regionSlug) Action detachVolume(Integer dropletId, String volumeId, String regionSlug) Action detachVolumeByName(Integer dropletId, String volumeName, String regionSlug) Action resizeVolume(String volumeId, String regionSlug, Double sizeGigabytes) Actions getAvailableVolumeActions(String volumeId) Action getVolumeAction(String volumeId, Integer actionId)
- Volumes
- Gson library updated to v2.7
- Added new endpoint support
- Released in v2.6
- Fix for delete droplet error #52
- Released in v2.5
- Added new endpoint support
/v2/tags/*
#48- Tags
Tags getAvailableTags(Integer pageNo, Integer perPage) Tag getTag(String name) Tag updateTag(String currentName, String newName) Delete deleteTag(String name) Response tagResources(String name, List resources) Response untagResources(String name, List resources)
- Tags
- Added new Attribute to the Image #49
- Fix for incorrect time zone returned from getActionInfo #47
- Added new endpoint support
- Released in v2.4
getDomainRecords
supports pagination params via PR #46
- Released in v2.3
Action enableDropletBackups(Integer dropletId)
Droplets createDroplets(Droplet droplet)
- Added
floating_ip_limit
attribute intoAccount
class updateDomainRecord()
method acceptsDomainRecord
as an input parameterper_page
parameter added to all the supported APIs- Floating IPs
FloatingIPs getAvailableFloatingIPs(Integer pageNo, Integer perPage) FloatingIP createFloatingIP(Integer dropletId) FloatingIP createFloatingIP(String region) FloatingIP getFloatingIPInfo(String ipAddress) Delete deleteFloatingIP(String ipAddress)
- Floating IPs Actions
Action assignFloatingIP(Integer dropletId, String ipAddress) Action unassignFloatingIP(String ipAddress) Actions getAvailableFloatingIPActions(String ipAddress, Integer pageNo, Integer perPage) Action getFloatingIPActionInfo(String ipAddress, Integer actionId)
- Released in v2.2
- Added compatibility for Android
- Applied latest API changes from DO, Account object & Snapshot status
- Released in v2.1
- Enhancements
- Libs version upgraded to latest
- Less objects generation
- Enhancements
- Released in v2.0
- Account
Account getAccountInfo()
- Actions
Actions getAvailableActions(Integer pageNo, Integer perPage) Actions getAvailableDropletActions(Integer dropletId, Integer pageNo, Integer perPage) Actions getAvailableImageActions(Integer imageId, Integer pageNo, Integer perPage) Action getActionInfo(Integer actionId)
- Droplets
Droplets getAvailableDroplets(Integer pageNo, Integer perPage) Kernels getAvailableKernels(Integer dropletId, Integer pageNo, Integer perPage) Snapshots getAvailableSnapshots(Integer dropletId, Integer pageNo, Integer perPage) Backups getAvailableBackups(Integer dropletId, Integer pageNo) Droplet getDropletInfo(Integer dropletId) Droplet createDroplet(Droplet droplet) Delete deleteDroplet(Integer dropletId) Droplets getDropletNeighbors(Integer dropletId, Integer pageNo) Neighbors getAllDropletNeighbors(Integer pageNo)
- Droplet Actions
Action powerCycleDroplet(Integer dropletId) Action powerOffDroplet(Integer dropletId) Action powerOnDroplet(Integer dropletId) Action rebootDroplet(Integer dropletId) Action rebuildDroplet(Integer dropletId, Integer imageId) Action renameDroplet(Integer dropletId, String name) Action resetDropletPassword(Integer dropletId) Action resizeDroplet(Integer dropletId, String size) Action resizeDroplet(Integer dropletId, String size, Boolean disk) Action restoreDroplet(Integer dropletId, Integer imageId) Action shutdownDroplet(Integer dropletId) Action takeDropletSnapshot(Integer dropletId) Action takeDropletSnapshot(Integer dropletId, String snapshotName) Action disableDropletBackups(Integer dropletId) Action enableDropletIpv6(Integer dropletId) Action enableDropletPrivateNetworking(Integer dropletId) Action changeDropletKernel(Integer dropletId, Integer kernelId)
- Images
Images getAvailableImages(Integer pageNo, Integer perPage) Images getAvailableImages(Integer pageNo, Integer perPage, ActionType type) Image getImageInfo(Integer imageId) Image getImageInfo(String slug) Image updateImage(Image image) Delete deleteImage(Integer imageId) Action transferImage(Integer imageId, String regionSlug) Action convertImage(Integer imageId) Images getUserImages(Integer pageNo, Integer perPage)
- Sizes
Sizes getAvailableSizes(Integer pageNo)
- Regions
Regions getAvailableRegions(Integer pageNo)
- Domains
Domains getAvailableDomains(Integer pageNo) Domain getDomainInfo(String domainName) Domain createDomain(Domain domain) Delete deleteDomain(String domainName)
- Domain Records
DomainRecords getDomainRecords(String domainName, Integer pageNo, Integer perPage) DomainRecord getDomainRecordInfo(String domainName, Integer recordId) DomainRecord createDomainRecord(String domainName, DomainRecord domainRecord) DomainRecord updateDomainRecord(String domainName, Integer recordId, String name) Delete deleteDomainRecord(String domainName, Integer recordId)
- Keys
Keys getAvailableKeys(Integer pageNo) Key getKeyInfo(Integer sshKeyId) Key getKeyInfo(String fingerprint) Key createKey(Key newKey) Key updateKey(Integer sshKeyId, String newSshKeyName) Key updateKey(String fingerprint, String newSshKeyName) Delete deleteKey(Integer sshKeyId) Delete deleteKey(String fingerprint)
Author
Jeevanandam M. - jeeva@myjeeva.com
Contributing
- Fork it
- Create your feature branch -
git checkout -b my-new-feature
- Implement your changes and apply Google Java Code Formatter
- Commit your changes -
git commit -am 'Added feature'
- Push to the branch -
git push origin my-new-feature
- Create new Pull Request
License
DigitalOcean API Client - MIT License.