Onboarding: Working with DigitalOcean Resources

Introduction

Welcome to DigitalOcean! We’re excited to have you on board. DigitalOcean offers a variety of products and services. From our simple-to-use Droplets, to our managed Kubernetes services, you can run a blog, a business, and everything between and beyond.

We’re here to help you get comfortable using different menus and workflows as you begin your next project. In this tutorial, you’ll generate an access token to use the API, and use doctl, the DigitalOcean command line interface.

Generating Personal Access Tokens and Using the DigitalOcean API

The DigitalOcean API allows you to manage your DigitalOcean resources. You can perform all the tasks that you would on the Control Panel with the DigitalOcean API. The tasks are detailed in the embedded video and the text that follows.

To use the API functionality, first create a Personal Access Token. On your Control Panel, navigate to the side navigation and press API:

Upon entering the API page, press the Generate New Token button:

Info: If you have an access token generated from a previous project or team, the Generate New Token button is on the right side of the page:

Enter a name for your token and set an expiration date.

If the Write option is not selected and is left unchecked, you will only be able to retrieve information from your infrastructure and you will not be able to make changes to it. Retrieving information without the ability to make changes is often referred to as a read-only status. To ensure that changes can be made to your project and resources, make sure that the Write scope selection is checked.

After you are finished with your selections, press the Generate Token button:

After generating your token, your API key will be revealed to you. It is good practice to treat your API key like a password. Make sure to copy this key and keep it in a secure location as it will only be shown to you once:

If your API key is lost or stolen, you can regenerate a new key. To do so, press the More button to the far right of the API key, then select Edit from the dropdown options:

You have the option to Update Token and Regenerate Token. You can update the token name and the write permissions.

Press the Regenerate Token button to create a new token associated with that token name. Regenerating a token will revoke access to the lost token. Be sure to save the new API token, as it will only be shown once:

With your token saved in a secure location, you’re ready to start using the API to access your DigitalOcean account resources. You can perform tasks with the curl command, a DigitalOcean API library for a specific language like Go, or use tools like Postman.

To learn how to use the API with curl, please refer to our documentation on How to Use the DigitalOcean API.

For demonstrative purposes in this tutorial, you will use Postman, a popular software that enables you to create and use APIs. With Postman, you will send an HTTP GET request to your account. You can learn more about using Postman with the Postman documentation.

In Postman, inside your Workspace, press the + plus button to access the API request:

From the API request page, select the GET request option, then enter the DigitalOcean API endpoint https://api.digitalocean.com/v2/ in the text box. Under the text box, select Authorization from the horizontal list.

The Authorization section includes a Type label with a dropdown menu in the left column. Select Bearer Token from the dropdown list. The scheme that the DigitalOcean API implements is Bearer tokens. Finally, put your API token into the token text box in the right column:

With your selections and token in place, you’re ready to interact with your API.

As an example, access your account information by appending account to the endpoint URL within the Postman workspace:

https://api.digitalocean.com/v2/account

After updating the endpoint with account, press the Send button. You’ll receive a response with your account information:

You can also access other endpoints, such as /droplets. To learn more about HTTP request methods and accessing various DigitalOcean resources through different endpoints, refer to the DigitalOcean API reference page.

In addition to accessing information, you can also create resources through the API. For example, to create a new Droplet with Postman, change the request method from GET to POST and update the endpoint to https://api.digitalocean.com/v2/droplets:

Under the endpoint text box, select Body, then choose the raw radio button. From the dropdown button on the right, select JSON:

By selecting JSON from the dropdown, you tell Postman to send data in the JSON format.

To create a new Droplet, you have to enter additional data in the body of this request. You need to include a name, the size of your Droplet, and an image. You can also enter the region of the datacenter you want to deploy in, but that is optional.

Enter the following JSON text into the body text area:

{
  "name": "Droplet-From-Api",
  "region": "nyc3",
  "size": "s-1vcpu-1gb",
  "image": "ubuntu-20-04-x64"
}

Here’s a brief description of the data passed in the POST request: "name": The name of your Droplet. You can name this whatever you would like to. In this example, the name is Droplet-From-Api. "region": If you know the datacenter region you would like to deploy in, like New York or San Francisco, you can add this data into your request body. If you don’t add a region, your Droplet will be deployed in any available region. Here, we added nyc3, which is in New York. For more information on DigitalOcean datacenters, you can review our datacenter availability matrix. "size": Enter a slug for the type of Droplet you would like to create. You can review different Droplet plans and sizes, as well as different images, by visiting the DigitalOcean API Slugs page. In this example, you’re creating a Droplet with one virtual CPU and one gigabyte of RAM. "image": DigitalOcean supports a few different images. In this example, you’re creating an Ubuntu 20.04 image. Refer again to the API slugs page to review available images.

After entering the JSON data, press Send to create your new Droplet. Upon creation, you’ll receive a JSON object in the response body just as you did when you made a GET request. If you navigate to your DigitalOcean Control Panel, your new Droplet will be listed.

The API enables you to manage your resources just like you can in the Control Panel alongside additional capabilities like enabling certain managed database features and much more.

Using the doctl Command Line Interface

Another way to interact with your account is with doctl, the official DigitalOcean command line interface (CLI). With doctl, you can interact with the DigitalOcean API. The doctl CLI supports most of the functionality found in the Control Panel. You can create, modify, and destroy resources like Droplets, Kubernetes clusters, and managed databases from the command line. The tasks are detailed in the embedded video and the text that follows.

To install doctl on your machine, follow our How to Install and Configure doctl documentation, which details specific instructions for different operating systems. doctl is available for Windows, macOS, and Linux.

After installing doctl, you can verify that the installation was successful by entering doctl version in your terminal:

doctl version

This output indicates that your installation was successful and complete:

doctl version 1.92.0-release
Git commit hash: 31aa0f4d

Like the API, you need a personal access token to use doctl. You can generate a new token or use the same token you generated previously. Make sure you have your token written down, then run the following command:

doctl auth init

Enter your access token when prompted:

Enter your access token: your_access_token
Validating token… OK

You can start working with your resources once your token has been authenticated. For example, you can display a list of currently deployed managed databases with this command:

doctl databases list

Your output, depending on how many databases you currently have, will provide an ID, a name, and other information about each database:

ID                                      Name                        Engine    Version    Number of Nodes    Region    Status    Size
59c53ec3-4d80-408b-8936-1808e366e7c7    db-postgresql-nyc1-69858    pg        14         1                  nyc1      online    db-s-1vcpu-1gb

In this example, you have a PostgreSQL database named db-postgresql-nyc1-69858 with 1 node, located in the nyc1 region.

You can also create a new managed database from doctl. For illustrative purposes, create a new MySQL managed database by running the following command:

doctl databases create mysql-from-doctl --engine mysql

With this command, you name the database mysql-from-doctl and set the database engine using the --engine flag. You can refer to the doctl CLI reference page on databases for additional information about flags.

You will receive an output similar to the following that indicates your database has been created:

Notice: Database created
ID                                      Name                Engine    Version    Number of Nodes    Region    Status      Size              URI                                                                                                                                          Created At
064613a3-74ed-4267-bc69-3006e0ac8f87    mysql-from-doctl    pg        14         1                  nyc1      creating    db-s-1vcpu-1gb    postgresql://doadmin:AVNS_GBdth9qL6nVjzq1JQvr@mysql-from-doctl-do-user-12000096-0.b.db.ondigitalocean.com:25060/defaultdb?sslmode=require    2023-01-13 20:58:11 +0000 UTC

In this example, you created a MySQL database named mysql-from-doctl that has 1 node and is located in the nyc1 region.

When you navigate to Databases in your DigitalOcean Control Panel, the new MySQL database you created will be listed:

You can use doctl to access and manage your DigitalOcean resources through the CLI. Although it is outside the scope of this tutorial, you can also use doctl to work with serverless functions.

Conclusion

Whether using doctl, the DigitalOcean API, or the DigitalOcean Control Panel to manage your resources, your infrastructure and resources are always displayed in the Control Panel. You can keep tabs on your active deployments with your Cloud Panel.

To continue learning about how to use DigitalOcean products, you can continue watching our Onboarding Series on YouTube.