DigitalOcean API Client

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:

• DigitalOcean API Client in Java

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)
      

  • Links and Meta information made available on POJO #84 @jeevatkm
  • Added method getAvailableDropletsByTagName #86 #jeevatkm
• Released in v2.15
  • Added CAA support in DomainRecord #81 @jeevatkm
  • Bug fix: Pagination fix for getAvailableRegions, getAvailableSizes, getAvailableDomains, and getAvailableKeys #80 @jeevatkm
• Released in v2.14
  • Added TTL field to DomainRecord PR #78 @rpardini
  • Added disk resize option when resizing a droplet PR #76 @majidalfifi
  • Bug fix: Priority in DomainRecord should be an Integer PR #79 @rpardini
• Released in v2.13
  • Added support for creating volumes from a snapshot ID PR #75 @benesch
  • DigitalOcean Rate-Limit headers handled gracefully PR #74 @benesch
• 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)
      

• 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)
      

• Released in v2.10
  • Removed unsupported API /v2/tags/$TAG_NAME refer DO changelog
• Released in v2.9
  • Added new API support delete droplet by tag name #61
    • Droplet

      Delete deleteDropletByTagName(String tagName)
      

• 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 meaningful

      getAvailableSnapshots(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)
      

  • Added volumes and tags attribute for create droplet #56
• 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)        
      

  • Gson library updated to v2.7
• 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)
      

  • Added new Attribute to the Image #49
  • Fix for incorrect time zone returned from getActionInfo #47
• 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 into Account class
  • updateDomainRecord() method accepts DomainRecord as an input parameter
  • per_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
• 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

1. Fork it
2. Create your feature branch - git checkout -b my-new-feature
3. Implement your changes and apply Google Java Code Formatter
4. Commit your changes - git commit -am 'Added feature'
5. Push to the branch - git push origin my-new-feature
6. Create new Pull Request

License

DigitalOcean API Client - MIT License.