We hope you find this tutorial helpful. In addition to guides like this one, we provide simple cloud infrastructure for developers. Learn more →

How To Use the DigitalOcean API v2

PostedJune 24, 2014 93.6k views API DigitalOcean

Introduction

In this tutorial, we will teach you how to get started with the DigitalOcean API v2.0. We will show you how to generate personal access tokens, which will be used for authentication, and show a few examples of how the API can be used.

The DigitalOcean API allows you to manage Droplets and other resources within the DigitalOcean cloud in a simple, programmatic way using conventional HTTP requests. The endpoints are intuitive and powerful, allowing you to easily make calls to retrieve information or to execute actions. Any action that you can perform through the DigitalOcean Control Panel (except personal access token actions) can also be performed with the API.

How To Generate a Personal Access Token

The first step to using the API is to generate a personal access token. Personal access tokens function like ordinary OAuth access tokens. They can be used instead of a password for DigitalOcean over HTTPS, or can be used to authenticate to the API over Basic Authentication. DigitalOcean tokens can be created with read or read-write scope. Write scope is required if you want to modify your account in any way (e.g. create or delete a droplet).

To generate an personal access token, start by logging in to DigitalOcean Control Panel.

Next, in the top menu, click on API.

In the Personal Access Tokens section, click the Generate new token button:

Generate New Token Button

You will be taken to the New Personal Access Token screen:

New Personal Access Token screen

Here, provide the following information:

  • Your desired token name (for your own reference)
  • Select the scope for this token (read or read/write)

Then click the Generate Token button.

Your token will be generated and presented to you on your Personal Access Tokens page. The actual token is the long string of numbers and letters, under the name:

Example Token

Be sure to record your personal access token now. It will not be shown again, for security purposes.

Now that you have generated a personal access token, you can use it like a password to use the API with your account.

Note: Remember to keep your tokens secret! They function similarly to passwords. Do not hardcode your token(s) into programs--use environmental variables. If a token becomes compromised, delete it to revoke that token's access.

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. The full API documentation is available here: DigitalOcean API v2.0 Documentation.

For all of the examples, we will assign our token to a variable called TOKEN. For example, in bash (replace the highlighted text with your own token):

  • export TOKEN=77e027c7447f468068a7d4fea41e7149a75a94088082c66fcf555de3977f69d3

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

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

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 14.04 droplet called "My-Droplet" in the NYC 2 data center, with 512MB RAM:

  • curl -X POST "https://api.digitalocean.com/v2/droplets" \
  • -d'{"name":"My-Droplet","region":"nyc2","size":"512mb","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 14.04 Droplets, one called "sub-01.example.com" and one called "sub-02.example.com" They both are in the NYC 2 data center, with 512MB RAM:

  • curl -X POST "https://api.digitalocean.com/v2/droplets" \
  • -d'{"names":["sub-01.example.com","sub-02.example.com"],"region":"nyc2","size":"512mb","image":"ubuntu-14-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 14.04 droplet called "My-Droplet" in the NYC 3 data center, 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 the highlighted word, "token", with your personal access token with write access):

create_droplet.rb
#!/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: '1gb', image: 'ubuntu-14-04-x64')
client.droplets.create(droplet)

Save and quit. Now 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 the highlighted word, "token", with your personal access token with write access, and replace the droplet ID):

delete_droplet.rb
#!/usr/bin/ruby

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

client.droplets.delete(id: 1916711)

Save and quit. Now run your delete script with the following command:

  • ruby delete_droplet.rb

You have initiated the delete action on the specified droplet.

Conclusion

Please visit the DigitalOcean API v2.0 Documentation to learn more about how you can leverage the API to enhance your Droplet and resource management!

Resources

15 Comments

Creative Commons License