How to Use the DigitalOcean API

Once you have a personal access token, you can start using the DigitalOcean API v2.0.

Using the API

We will cover some example API requests, using the curl command. This will allow us to demonstrate various endpoints in a simple, textual format. For all of the examples, we will assign our token to a variable called TOKEN. For example, in Bash, you can use the following command. Make sure to substitute in your own token.

export TOKEN=77e027c7447f468068a7d4fea41e7149a75a94088082c66fcf555de3977f69d3

If you attempt access the API with a token that does not exist, you will see the following error message:

{
  "id":"not_found",
  "message":"The resource you were accessing could not be found."
}

Make sure you copy and paste your token correctly.

Example: List all Actions

To list all of the actions that have been executed on the current account, send a GET request to /v2/actions:

curl -X GET "https://api.digitalocean.com/v2/actions" \
	-H "Authorization: Bearer $TOKEN"

Example: List all Droplets

To list all Droplets in your account, send a GET request to /v2/droplets:

curl -X GET "https://api.digitalocean.com/v2/droplets" \
	-H "Authorization: Bearer $TOKEN"

Example: Create a New Droplet

To create a new Droplet, send a POST request to /v2/droplets. For a full list of attributes that must be set to successfully create a Droplet, see the full documentation. The following example creates an Ubuntu 16.04 Droplet called “My-Droplet” in the NYC3 datacenter, with 1 GB RAM:

curl -X POST "https://api.digitalocean.com/v2/droplets" \
	-d'{"name":"My-Droplet","region":"nyc3","size":"s-1vcpu-1gb","image":"ubuntu-14-04-x64"}' \
	-H "Authorization: Bearer $TOKEN" \
	-H "Content-Type: application/json"

Note: This request, like any other request that makes a change to your account, requires that your token has “write” scope assigned to it.

Example: Create Multiple Droplets

You can also create multiple Droplets with the same attributes using a single API request by sending a POST to /v2/droplets. Instead of providing a single name in the request, provide an array of names. The following example creates two Ubuntu 16.04 Droplets, one called “sub-01.example.com” and one called “sub-02.example.com” They both are in the NYC3 datacenter, with 1 GB RAM:

curl -X POST "https://api.digitalocean.com/v2/droplets" \
	-d'{"names":["sub-01.example.com","sub-02.example.com"],"region":"nyc3","size":"s-1vcpu-1gb","image":"ubuntu-16-04-x64"}' \
	-H "Authorization: Bearer $TOKEN" \
	-H "Content-Type: application/json"

Using Wrappers For the API

There are a variety of wrappers in different languages for the API. Wrappers can be useful for integrating the API into a script or application, and can often be found on GitHub.

Here is an example of using the official DigitalOcean Ruby wrapper, DropletKit. We will demonstrate how to use DropletKit to create and delete a Droplet, but be sure to check the documentation for more functionality.

Ensure that you have RubyGems installed, then use the following command to install DropletKit:

gem install droplet_kit

DropletKit Example: Create a New Droplet

We will demonstrate how to use DropletKit to create an Ubuntu 16.04 Droplet called “My-Droplet” in the NYC3 datacenter, with 1 GB RAM.

Create a new ruby script called create_droplet.rb with the following command:

vi create_droplet.rb

And paste in the following code (replace token in the highlighted line with your personal access token with write access):

#!/usr/bin/ruby

require 'droplet_kit'
token='token'
client = DropletKit::Client.new(access_token: token)

droplet = DropletKit::Droplet.new(name: 'example.com', region: 'nyc3', size: 's-1vcpu-1gb', image: 'ubuntu-14-04-x64')
client.droplets.create(droplet)

Save and quit by pressing the ESCAPE key, then typing :wq followed by ENTER. Once you’ve exited, run your create script with the following command:

ruby create_droplet.rb

You have initiated the creation of the specified Droplet.

DropletKit Example: Delete a Droplet

We will demonstrate how to use DropletKit to delete a Droplet with the ID 1916711.

Create a new ruby script called delete_droplet.rb with the following command:

vi delete_droplet.rb

And paste in the following code (replace token in the highlighted line with your personal access token with write access, and replace the Droplet ID):

#!/usr/bin/ruby

require 'droplet_kit'
token='token'
client = DropletKit::Client.new(access_token: token)

client.droplets.delete(id: 1916711)

Save and quit by pressing the ESCAPE key, then typing :wq followed by ENTER. Now run your delete script with the following command:

ruby delete_droplet.rb

You have initiated the delete action on the specified Droplet.

More Information