DigitalOcean API — Capabilities, Usage, and Building Guide

DigitalOcean API — Capabilities, Usage, and Building Guide

Metadata

At a Glance

DigitalOcean exposes a REST API v2 for managing Droplets, App Platform, databases, Spaces, Kubernetes, domains, load balancers, firewalls, and more. Authentication uses personal access tokens (Bearer). The platform is built for simplicity and predictable pricing — ideal for solo developers and small teams who want AWS-like capabilities without the complexity. Spaces is S3-compatible; doctl is the official CLI; Node.js developers use the AWS SDK with Spaces or community libraries for the main API.

Quotes

"Keep your tokens secret. They function like passwords. Do not hard code your tokens into programs where they may accidentally be released in version control and are harder to rotate. Instead, use environment variables."

— DigitalOcean API Documentation [1]

"The Spaces API is interoperable with the AWS S3 API, meaning you can use existing S3 tools and libraries with it."

— DigitalOcean Docs [2]

"App Platform is a fully managed Platform-as-a-Service (PaaS) that deploys applications from Git repositories or container images. It automatically builds, deploys, and scales components while handling all underlying infrastructure."

— DigitalOcean App Platform Docs [3]

"DigitalOcean Droplets are often praised for their simplicity and developer-friendly interface, making them a great choice for individuals and small to medium-sized businesses. AWS EC2 offers a wider range of instance types and services, which can be more suitable for large enterprises with complex requirements. In terms of pricing, DigitalOcean is generally more affordable for comparable resources."

— DigitalOcean Pricing FAQ [4]

"doctl does not support the DigitalOcean Spaces API. However, because the Spaces API is S3-compatible, you can use S3-compatible command line tools like s3cmd to manage Spaces."

— DigitalOcean doctl Docs [5]

Sam's TLDR

DigitalOcean's API is straightforward: REST v2, bearer token auth, and well-documented endpoints for everything from spinning up Droplets to managing Kubernetes. The platform leans into predictability — flat monthly pricing, simple resource model, no hidden fees. For a solo dev or small team, it's a sweet spot between the bare-metal chaos of DIY VPS and the overwhelming breadth of AWS. Spaces is basically S3 — use the AWS SDK. App Platform deploys from Git or Docker; you can define apps in YAML and push via API or doctl. Managed databases (Postgres, MySQL, MongoDB, Valkey, etc.) start around $15/mo. The main gotchas: doctl doesn't do Spaces (use s3cmd or the AWS SDK), rate limits exist (doctl auto-retries on 429), and custom token scopes mean you can't edit scope after creation. Overall, it's a strong fit for static sites, side projects, and small production workloads — especially if you value simplicity and predictable bills.

Key Points

• REST API v2 — Base URL https://api.digitalocean.com/v2. All resources (Droplets, apps, databases, etc.) use conventional HTTP requests with JSON [1][6].
• Personal access tokens — Bearer auth via Authorization: Bearer . Custom scopes allow granular permissions (droplet:create, database:read, app:update, etc.). Token scopes cannot be edited after creation [1].
• Rate limits — API returns 429 when rate limited. doctl automatically retries 429 and 500-level errors; retry count configurable via --http-retry-max or DIGITALOCEAN_HTTP_RETRY_MAX [5].
• Four APIs — Main DigitalOcean API (Droplets, apps, DBs, K8s, etc.), Spaces API (S3-compatible REST/XML), OAuth API (third-party auth), Metadata API (Droplet self-discovery at 169.254.169.254) [1][2].
• Droplets — Linux VMs billed per-second (60s min or $0.01). Basic plans from $4/mo. Use /v2/droplets, /v2/sizes (plans), /v2/images. Resize, snapshot, destroy via actions [6][7].
• App Platform — Deploy from GitHub/GitLab, static sites, or Docker images. YAML app spec for API/doctl. Static sites free tier (3 apps, 1 GiB transfer). Paid plans from $5/mo per component [3][8].
• Managed Databases — Postgres, MySQL, MongoDB, Valkey (Redis-compatible), Kafka, OpenSearch. From ~$15/mo. API: /v2/databases. Daily backups, VPC, HA with standby nodes [9][10].
• Spaces — S3-compatible object storage. $5/mo base, 250 GiB included, 1,024 GiB outbound. CDN included. Use AWS S3 SDK or s3cmd. Not managed by doctl [2][11].
• Kubernetes (DOKS) — Managed K8s, free control plane. From $12/mo for worker nodes. API: /v2/kubernetes [12].
• doctl — Official CLI. brew install doctl. Supports Droplets, K8s, apps, databases, firewalls, load balancers, domains. Does not support Spaces [5].
• Node.js — No official DigitalOcean Node SDK. Use @aws-sdk/client-s3 for Spaces. For main API, use axios/fetch with token or community packages like digitalocean on npm.

Full Summary

1. API Overview — REST v2, Auth, Rate Limits

Basics

• Base URL: https://api.digitalocean.com/v2
• Content-Type: application/json
• Authentication: Authorization: Bearer

Personal Access Tokens

• Created in Control Panel → API → Tokens
• Scopes: Read Only, Full Access, or Custom (e.g., droplet:create, app:read, database:delete)
• CRUD scopes map to actions: Create, Read, Update, Delete per resource type
• Tokens expire; secret shown once only
• Scope cannot be edited after creation [1]

Rate Limits

• 429 Too Many Requests when exceeded
• doctl retries 429 and 5xx by default; configurable via --http-retry-max or DIGITALOCEAN_HTTP_RETRY_MAX (set 0 to disable) [5]

---

2. Droplets — Create, Manage, Resize, Snapshot

Key Endpoints Example Use Cases

• Provision dev/staging VMs via CI
• Spawn temporary Droplets for batch jobs (per-second billing)
• Snapshot before major changes; restore from snapshot

Pricing (approximate)

Bandwidth: free outbound (500–11,000 GiB depending on plan); overage $0.01/GiB. Inbound free [7].

Gotchas

• Billing continues when Droplet is powered off; destroy to stop
• Per-second billing, 60s min or $0.01
• Snapshots billed at $0.06/GB/month

---

3. App Platform — Git, Static, Docker

Capabilities

• Deploy from GitHub, GitLab, or container images (Docker)
• Static sites (HTML, SSG output)
• Web services, workers, cron jobs
• YAML app spec for API/doctl deployment

Key Endpoints Example Use Cases

• CI/CD: push app spec via API after build
• Static site hosting (free tier: 3 apps, 1 GiB each)
• Full-stack app from monorepo (services + static)

Pricing Gotchas

• Renaming a component restarts the 28-day billing window
• Development databases: $7/mo per 512MB
• XL build resources now default; xl-build flag deprecated [3][8]

---

4. Managed Databases — Postgres, MySQL, Redis, MongoDB, etc.

Engines

PostgreSQL, MySQL, MongoDB, Valkey (Redis-compatible), Kafka, OpenSearch

Key Endpoints Example Use Cases

• Provision Postgres/MySQL for app backends
• Valkey (Redis) for caching/sessions
• MongoDB for document storage

Pricing

Storage: $0.215/GiB/mo (varies by engine)

Gotchas

• Managed Caching (Redis) being discontinued June 2025; migrate to Valkey
• Up to 2,000 trusted IPs (except MongoDB)
• Configure client reconnection for failover (5–10s outages possible) [9][10]

---

5. Spaces — S3-Compatible Object Storage

API

• REST XML API compatible with AWS S3
• Use AWS SDK (@aws-sdk/client-s3) or s3cmd
• Endpoint: https://.digitaloceanspaces.com

Example Use Cases

• Static site hosting (with CDN)
• File uploads, backups, media storage
• CI artifact storage

Pricing

CDN included. Same-region Droplet → Spaces transfer free for some region pairs [11].

Gotchas

• doctl does not manage Spaces; use s3cmd or AWS SDK
• Cold Storage: $0.007/GiB, retrieval $0.01/GiB; 30-day min retention
• New accounts with billing issues may lose Spaces access within ~7 days [11]

---

6. Kubernetes (DOKS)

Key Endpoints Example Use Cases

• Managed K8s with free control plane
• Integrates with DO load balancers, volumes, GPU Droplets

Pricing

• Control plane: free
• Worker nodes: from ~$12/mo
• Free bandwidth allowance included [12]

---

7. Domains and DNS

Key Endpoints Example Use Cases

• Point domains at Droplets, load balancers, App Platform
• Integrates with Let's Encrypt for SSL
• Free DNS management [13]

---

8. Load Balancers and Networking

Load Balancers

• Regional or Global
• API: /v2/load_balancers
• From $12/mo
• Network load balancers (TCP/UDP) in GA [14]

VPC

• Private networks; free
• VPC peering: intra-DC free, inter-DC $0.01/GiB
• NAT Gateway: $40/node, 100 GiB included [15]

Firewalls

• Cloud Firewalls: free
• API: /v2/firewalls

---

9. Monitoring and Alerts

Monitoring

• Free, opt-in
• Droplet metrics: CPU, memory, bandwidth
• Alerts via email or Slack

Uptime

• One free uptime check per account
• Alerts on downtime/latency [16]

---

10. doctl and Client Libraries

doctl

• Install: brew install doctl (macOS)
• Auth: doctl auth init
• Commands: compute, apps, databases, kubernetes, vpcs, etc.
• No Spaces support — use s3cmd [5]

Client Libraries

• Go: github.com/digitalocean/godo (official)
• Node.js: no official SDK; use axios/fetch or community digitalocean npm package
• Spaces: @aws-sdk/client-s3 with custom endpoint

---

11. Pricing Overview

---

DigitalOcean vs. AWS/GCP for Small–Medium Projects

Takeaway: DigitalOcean excels when you want fast setup, predictable bills, and a narrow but sufficient feature set. AWS/GCP make sense when you need specific services (e.g., Lambda, BigQuery) or global multi-region complexity [4].

---

Best Practices for Solo Developer / Small Team

Token security — Use env vars, never commit tokens. Rotate periodically [1].

Custom scopes — Grant least privilege; e.g., droplet:create only for provisioning scripts.

Infrastructure as code — Use app specs (YAML) for App Platform; Terraform/Pulumi for Droplets and networking.

Billing alerts — Set up alerts to avoid surprises.

VPC by default — New resources go in VPC; private traffic doesn't count against bandwidth.

Reconnection logic — For managed databases, implement retry/reconnect for brief failover windows [9].

doctl for day-to-day — Faster than API for ad-hoc tasks; script API for automation.

---

Deploy a Static Site via the API

Option A: App Platform

Create app spec YAML with static_sites component, github repo, source_dir, output_dir (e.g., build).

POST /v2/apps with the spec.

Trigger deployment: POST /v2/apps/:id/deployments.

Option B: Spaces

Create Space via Control Panel or Spaces API (S3-compatible).

Upload built files with aws s3 sync build/ s3://bucket-name/ (or AWS SDK).

Enable CDN and optional custom domain.

Configure index/error documents for SPA if needed.

---

Set Up a VPS with Docker via the API

Create Droplet — POST /v2/droplets with:

- image: docker-24-04 or docker-24-04-x64 (Docker 1-Click image)

- size: e.g., s-1vcpu-1gb

- region, name, ssh_keys

Wait for creation — Poll /v2/droplets/:id or use actions API.

User data (optional) — Pass cloud-init in user_data to install Docker, run docker-compose, etc.

Connect — SSH with key; Docker pre-installed on 1-Click image.

Alternatively, use a standard Ubuntu image and provide user_data with Docker install script.

---