Java

README.md

DigitalOcean API Client Build Status Version License

v2.13 released and tagged on Nov 18, 2017

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.13</version>
</dependency>

Gradle/Grails dependency

compile 'com.myjeeva.digitalocean:digitalocean-api-client:2.13'

Groovy Grape

@Grapes(
@Grab(group='com.myjeeva.digitalocean', module='digitalocean-api-client', version='2.13')
)

Scala SBT

libraryDependencies += "com.myjeeva.digitalocean" % "digitalocean-api-client" % "2.13"

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:

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.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
    • Fixed bug - 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
  • 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 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.