DropletKit: the deprecated Ruby client for the DigitalOcean API

An official client that is no longer being developed

DropletKit is a Ruby client for the DigitalOcean V2 API, and it was the official client, published under the digitalocean organisation with a gem of the same name. The important thing about it now is the notice at the very top of the README, which says the library is deprecated and no longer actively maintained. New applications should use the DigitalOcean API directly or a supported SDK, and the notice says plainly that there is no official Ruby SDK.

The deprecation section is specific about what each of those statements means in practice. The status is deprecated with no new features and no new API coverage, and only critical security fixes will be made. The published versions on RubyGems remain available and no new releases are planned. Forks are permitted under the MIT licence, which is the clause that decides what happens to this code: anyone can continue it, and anyone can build the same client themselves on top of the API.

The release history shows what that means in practice. Version 3.22.0 was published on 2025-02-26, version 3.21.0 on 2024-05-17 and version 3.20.0 on 2023-08-21, and the last push to the repository was on 2026-06-11. So the gem is not frozen in the sense of being broken, but it will not learn about a new DigitalOcean resource, and that is a permanent gap rather than a delay.

The migration advice is to call the API reference directly, or to use Godo in another language, with the specific libraries named being Godo for Go, PyDo for Python and DoTs for TypeScript.

The client, the token and the two timeouts

The entry point is a client object, and the only required argument is an access token, which you generate in the DigitalOcean control panel.

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

Two optional timeout settings are worth knowing about, because the default behaviour of an HTTP client is not always what you want when the remote end is an API that provisions machines. The open_timeout is described as the time to first byte in seconds, and the timeout is the response timeout in seconds:

require 'droplet_kit'
client = DropletKit::Client.new(
  access_token: 'YOUR_TOKEN',
  open_timeout: 60, # time to first byte in seconds
  timeout:      120, # response timeout in seconds
)

The distinction between the two matters for long running operations, since creating a droplet or rebuilding a database cluster can hold the connection open for a while, and a client that times out at 60 seconds in the middle of a provisioning request is a client that reports failures that are not failures.

There is also a custom User-Agent option, which passes a user_agent value at client initialisation, and the README describes it as a way to include a header beyond what DropletKit uses by default.

Everything else in the design is about resources rather than about the client, and that is where the library's shape comes from.

Rate limit handling, and the three knobs that control it

DropletKit handles the DigitalOcean API rate limits for you, and the behaviour is documented in enough detail to reason about.

The API has a burst limit and an hourly limit, and they are treated differently. When the burst rate limit is reached, DropletKit waits according to the value of the API response's Retry-After header, and typically that wait is less than one minute. When the hourly rate limit is hit, an error is raised instead, because waiting out an hourly limit is not something a client should do silently.

By default a rate limited request is retried three times before an error is returned, and setting the retry_max config value to zero disables the retry behaviour entirely so that any rate limit raises immediately. There is a third knob, retry_wait_min, which is the number of seconds the client waits after the Retry-After time has elapsed, and it defaults to zero.

require 'droplet_kit'
client = DropletKit::Client.new(access_token: 'YOUR_TOKEN', retry_max: 3, retry_wait_min: 1)

For a script that lists resources in a loop, those three settings are the difference between a job that finishes and a job that dies halfway through, and the default of zero extra wait is sensible for a client that is already honouring the server's own instruction.

It is worth noting what this does not cover. The client respects the limits that the API documents, and it cannot know about limits imposed by something else in front of the API, such as a shared NAT gateway or a proxy, so a script that runs from several machines at once can still hit a limit that no single machine exceeded.

Resources as methods, objects as plain Ruby

The design is described as a strict one, with resources as methods on your client. Droplets are reached through the client:

client = DropletKit::Client.new(access_token: 'YOUR_TOKEN')
client.droplets #=> DropletsResource

What you get back are plain old Ruby objects containing the information the API returned. The interesting part is the laziness: for actions that return multiple objects, the request is not executed until the result is accessed.

client.droplets.all
# => #<DropletKit::PaginatedResource:0x000000010d556c3a>

client.droplets.all.first
# => <DropletKit::Droplet {:@id=>1, :@name=>"mydroplet", ...}>

client.droplets.all.map(&:id)
# => [1]

So calling all does not immediately spend your rate limit, and the request happens when you reach into the result. That is a real behavioural difference from a client that fetches eagerly, and it is the kind of thing that matters in a script that builds a collection of several calls.

Writing is explicit rather than magical. To create a droplet you instantiate the object yourself and persist it through the resource, and the object is a plain constructor with keyword arguments:

client = DropletKit::Client.new(access_token: 'YOUR_TOKEN')
droplet = DropletKit::Droplet.new(name: 'mysite.com', region: 'nyc2', image: 'ubuntu-14-04-x64', size: 's-1vcpu-1gb')
created = client.droplets.create(droplet)

To read one back, you ask the resource for it by id. The README is explicit that saving objects is your responsibility, which is a deliberate division of labour: the library does not maintain a local database of what it created.

The resource catalogue, and the actions each one offers

The README then lists the resources and their supported actions, which is the part to scan for the API surface you need.

The CDN resource is reached through client.cdns, and a CDN object carries an origin, a time to live, a custom domain and a certificate id. Its actions are find, all, create, update_ttl, update_custom_domain, flush_cache and delete, and the flush cache call takes a list of file patterns, so you can invalidate everything with a wildcard or a specific path.

The certificate resource is reached through client.certificates, with find, all, create and delete.

The database resource is the richest of the three shown. It is reached through client.databases, and a DatabaseCluster object carries a name, an engine, a version, a region, a size, a number of nodes and tags, which is the whole shape of a managed database request in one constructor call. Its actions are the ones a cluster needs over its life: find_cluster, all_clusters, create_cluster, resize_cluster, migrate_cluster, set_maintenance_window, update_maintenance_window, list_backups and restore_from_backup.

The pattern across all three is the same, and it is the pattern you will feel throughout the library: the resource object is constructed with plain data, the client method performs the action, and the return value is a plain object. There is no client-side validation, no builder DSL and no local state, which is exactly what makes a deprecated client still pleasant to use and also what makes it a thin layer that another library could reproduce.

The README is the reference for the full list of resources and actions, and the CHANGELOG in the repository is where you would look to see whether an action you rely on ever changed shape.

The repository, and what a fork would inherit

The tree is a conventional Ruby gem: a lib/ directory, a spec/ directory, a droplet_kit.gemspec, a Gemfile, a Rakefile, a CHANGELOG.md and a RELEASE.md.

The tooling tells you how the project was maintained. The .rspec file configures RSpec, the .rubocop.yml and .rubocop_todo.yml pair show RuboCop with a file of accepted offences, which is the usual way a project records the rules it has not fixed yet rather than disabling them silently. There is a .whitesource configuration, which is the security scanning service, so dependency vulnerabilities were being tracked while the project was alive.

The CI badge points at a GitHub Actions build workflow on the main branch, and the topic tags include hacktoberfest, so the project has taken outside contributions through the October event.

For anyone considering a fork, the MIT licence in LICENSE.txt is the permission slip, and the pieces a fork would need to rebuild are the resource definitions, the request layer with its retry behaviour, and the object model. The latter two are the parts that are not visible in the README, which is why reading the source is the first task for anyone who intends to continue this rather than simply keep using it.

The practical advice for a team still on DropletKit is to keep the version you have, or to move to the latest published one, and to plan the migration at a moment when the DigitalOcean API is not changing underneath you. What the project will not give you is new endpoints, and the API reference is the thing to read when you need to know whether the gem can still do what you need it to do.

Editorial conclusion

DropletKit is the right choice for an existing Ruby application that already depends on it, where a rewrite is not worth the risk, because the published versions remain available and only critical security fixes will land. It is the wrong choice for a new project, since no new API coverage is coming and the DigitalOcean API has certainly moved on since version 3.22.0, and it is the wrong choice for a team that wants supported SDKs, since the project itself says to use the API directly or one of the TypeScript, Go or Python libraries instead. Before you start a new integration, read the deprecation section and pick a path deliberately, and if you keep DropletKit, pin the version you tested with and watch the CHANGELOG for the critical security fixes that are all that will be released.

Frequently asked questions

Official sources

1. digitalocean/droplet_kit on GitHub
2. Issues
3. License: MIT
4. README
5. Releases