DigitalOcean Changelog

Introducing the Projects API Beta

Date: October 16, 2018

Tagged In: API v2

Author Andrew Starr-Bochicchio

Today, we are launching a beta of our new Projects API. Projects enable you to group your resources in ways that align with the applications you host on DigitalOcean, and now you can do so via our API as well. This initial release includes the ability to:

  • Create, list, retrieve, update, and delete Projects
  • Assign existing resources to a Project
  • List resources in a Project

Additionally, we’ve added beta support for Projects to our official clients (Droplet Kit, godo, and doctl).

You can create a new project by sending a POST request to the /v2/projects endpoint including a body like:

{
  "name": "my-web-api",
  "description": "My website API",
  "purpose": "Service or API",
  "environment": "Production"
}

To assign resources to a project, send a POST request to /v2/projects/$PROJECT_ID/resources including a list of those resources in the body:

{
  "resources": [
    "do:droplet:123456",
    "do:floatingip:192.168.99.100",
    "do:space:static-assets",
    "do:volume:0e250b2a-8a01-11e8-96ae-0242ad114410"
   ]
}

Resources are identified by uniform resource names or URNs, a string consisting of the type of resource and its unique identifier. A valid URN has the following format: do:resource_type:resource_id. For the full details, see the API reference documentation for both Projects and Project Resources.

Note that as this is a beta release, we may make additional changes based on your feedback. So let’s us know how you’re using projects, and please follow along with the API changelog for updates.

Support for Spaces CDN Endpoints

Date: September 27, 2018

Tagged In: API v2

Author Andrew Starr-Bochicchio

Today’s release brings Content Delivery Network (CDN) support to Spaces, DigitalOcean’s object storage solution. This can be configured and managed using our API. By sending requests to /v2/cdn/endpoints, you can list, create, or delete CDN endpoints as well as purge cached content.

To enable the CDN for your Space, send a POST request to /v2/cdn/endpoints. In the JSON body of your request, specify the origin of your content and the desired TTL. For example:

{
  "origin": "static-images.nyc3.digitaloceanspaces.com",
  "ttl": 3600
}

Currently, the origin must be a DigitalOcean Space.

To purge cached content from a CDN endpoint, send a DELETE request to /v2/cdn/endpoints/$ENDPOINT_ID/cache. The body of the request should include a files attribute containing a list of cached file paths to be purged. A path may be for a single file or may contain a wildcard (*) to recursively purge all files under a directory. When only a wildcard is provided, all cached files will be purged. For example, the body of your request might look like:

{
  "files": [
    "assets/img/hero.png",
    "assets/css/*"
  ]
}

For additional details, see the API reference documentation for managing CDN endpoints.

Support for Custom Images and Image Tagging

Date: September 25, 2018

Tagged In: API v2

Author Andrew Starr-Bochicchio

Today DigitalOcean released support for uploading custom images, enabling you to create Droplets based on your own Linux virtual machine images. Our image management API has been extended with support as well. By sending a POST to the /v2/images endpoint, you can create a new custom image. The request must contain a url attribute pointing to where the image can be downloaded. The image itself may be in the raw, qcow2, vhdx, vdi, or vmdk format. It can be compressed using gzip or bzip2 but must be smaller that 100 GB after being decompressed. For example, the body of you request might look like:

{
  "name": "ubuntu-18.04-minimal",
  "url": "http://cloud-images.ubuntu.com/minimal/releases/bionic/release/ubuntu-18.04-minimal-cloudimg-amd64.img",
  "distribution": "Ubuntu",
  "region": "nyc3",
  "description": "Cloud-optimized image w/ small footprint",
  "tags": [
    "base-image",
    "prod"
  ]
}

To make organizing your images easier, we’ve also extended tagging support to custom images as well as Droplet snapshots. For additional details, see the API reference documentation for creating custom images and tagging resources.

Deprecating tag.resources.droplets.last_tagged, adding a last_tagged_uri and a count for all resources

Date: September 5, 2018

Tagged In: API v2

Author Hugo Corbucci

When listing or getting tags by sending a GET request to /v2/tags or /v2/tags/$TAG_NAME, the response payload currently includes a last_tagged value inside the tag’s resources.droplets containing a full representation of the resource. This payload is considerably nested and adds additional overhead to the request. In order to improve performance as well as lay the groundwork for bring tagging support to additional resources, this attribute is being deprecated. Beginning March 1st, 2019 last_tagged will no longer be populated in favor of the new last_tagged_uri attribute introduced today.

For all resources (and each resource type supported), the last_tagged_uri attribute contains a string indicating the URI which can be used to retrieve details about that specific resource. If you need information about the last tagged resource specifically, issuing another call to that URI will provide you with all the data for that resource.

Additionally, a count attribute describing how many resources overall have been tagged with the tag in question has been added. Each individual resource type will continue providing a count attribute.

If you need guidance on transitioning from using last_tagged to using of the new last_tagged_uri attribute , please feel free to reach out to the team by opening a support ticket.

Create Domains Without Providing an IP Address

Date: June 22, 2018

Tagged In: API v2

Author Andrew Starr-Bochicchio

New Domain resources can now be created via the DigitalOcean v2 API without providing an IP address. The previous behavior, which would automatically create an A record pointing to the apex domain, will be retained for backwards-compatibility when an IP address is provided.

This example demonstrates how to create a new domain without providing an IP address:

curl -X POST -H "Content-Type: application/json" \
    -H "Authorization: Bearer $DIGITALOCEAN_API_TOKEN" \
    -d '{"name":"example.com"}' \
    "https://api.digitalocean.com/v2/domains"

For more information, see the full Domains API documentation.

Block Storage Volumes Now Support Automatic Filesystem Formatting

Date: May 22, 2018

Tagged In: API v2

Author Andrew Starr-Bochicchio

The /v2/volumes endpoint has been updated to support automatically formatting the filesystem of newly created Block Storage volumes. Volume resources now expose two new attributes: filesystem_type and filesystem_label. They can be used to specify the filesystem and the label to be applied. Currently, the available filesytem types are ext4 and xfs.

For example, here is a request creating a new volume formatted with an EXT4 filesystem:

  curl -X POST \
    -d '{"name":"volume-nyc3-01","region":"nyc3","filesystem_type":"ext4","filesystem_label":"example","size_gigabytes": 100}' \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
    https://api.digitalocean.com/v2/volumes

Additionally, Ubuntu, Debian, Fedora, Fedora Atomic, and CentOS Droplets created on or after April 26, 2018 will now automatically mount volumes with pre-formatted filesystems when attached. Attaching pre-formatted volumes to other Droplets is not recommended. When the filesystem_type attribute is not provided, volumes will continue to be presented as raw block devices and require additional configuration.

When retrieving an existing Block Storage volume, filesystem_type and filesystem_label will reflect the current filesystem and label used on the volume even if these were applied manually.

For more information, see the full API documentation for Block Storage Volumes.

Let's Encrypt Support for Certificate resources

Date: May 8, 2018

Tagged In: API v2

Author Andrew Starr-Bochicchio

Today, DigitalOcean released a number of Load Balancer improvements including support for using SSL/TLS certificates automatically generated by Let’s Encrypt. Our Certificate management API has been updated to support automatically generating Let’s Encrypt certificates in addition to uploading custom, user-generated certificates.

A request to generate a new SSL/TLS certificate using Let’s Encrypt would look like:

  curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $DO_TOKEN" \
    -d '{"name": "le-cert-01", "type": "lets_encrypt", "dns_names": ["www.example.com","example.com"]}' \
    "https://api.digitalocean.com/v2/certificates"

The new type attribute must be set to lets_encrypt when using Let’s Encrypt. If omitted, it will default to custom in order to maintain backwards compatibility. For additional details, see the Certificate management API reference documentation.

For more information on how to use Let’s Encrypt with DigitalOcean Load Balancers, see this tutorial on our community site.

New Size Slugs for Droplet Plan Changes

Date: January 16, 2018

Tagged In: API v2

Author Andrew Starr-Bochicchio

Today, we announced wide-ranging changes to our Droplet plans, bringing improved resources across the board. These new plans are now available via the API and can be referenced using their respective size slugs.

Size slugs are human-readable strings used to specify the type of Droplet in certain API requests. In the past, size slugs were typically based on the amount of RAM provided with the plan (e.g. 1gb). Moving forward, we are standardizing on a format comprised of the identifier for the Droplet’s class, the vCPU count, and the amount of RAM in order to provide more flexibility in the plans we are able to offer you. For example, our new $5 per month Standard Droplet comes with 1 vCPU and 1 GB of RAM. So its size slug is: s-1vcpu-1gb

Applications and scripts with hard-coded size slugs must be updated to take advantage of these new plans. In order to provide a transition period, 1st Generation Droplet plans will continue to be available via the API using the legacy size slugs. We will provide additional notice before their removal.

The table below shows the new 2nd Generation Standard Droplet plans along with their corresponding size slug. For always up-to-date information on available plans and pricing, please see our pricing page.

Class Slug vCPUs RAM Disk Transfer Monthly Price
Standard s-1vcpu-1gb 1 1 GB 25 GB 1 TB $5
Standard s-1vcpu-2gb 1 2 GB 50 GB 2 TB $10
Standard s-1vcpu-3gb 1 3 GB 60 GB 3 TB $15
Standard s-2vcpu-2gb 2 2 GB 60 GB 3 TB $15
Standard s-3vcpu-1gb 3 1 GB 60 GB 3 TB $15
Standard s-2vcpu-4gb 2 4 GB 80 GB 4 TB $20
Standard s-4vcpu-8gb 4 8 GB 160 GB 5 TB $40
Standard s-6vcpu-16gb 6 16 GB 320 GB 6 TB $80
Standard s-8vcpu-32gb 8 32 GB 640 GB 7 TB $160
Standard s-12vcpu-48gb 12 48 GB 960 GB 8 TB $240
Standard s-16vcpu-64gb 16 64 GB 1,280 GB 9 TB $320
Standard s-20vcpu-96gb 20 96 GB 1,920 GB 10 TB $480
Standard s-24vcpu-128gb 24 128 GB 2,560 GB 11 TB $640
Standard s-32vcpu-192gb 32 192 GB 3,840 GB 12 TB $960

Available Droplet plans, the resources they provide, and the size slug used to identify them can be accessed programmatically by querying the /v2/sizes endpoint.

CAA Support for Domain Record resources

Date: September 13, 2017

Tagged In: API v2

Author Andrew Starr-Bochicchio

Domain Record resources have been updated to add support for CAA records. As specified in RFC-6844, this record type can be used to specify which certificate authorities (CAs) are permitted to issue certificates for a domain.

For example, in order to restrict TLS/SSL certificate creation for example.com to letsencrypt.org, you would use a request like:

  curl -X POST \
    -d '{"type":"CAA","name":"@","data":"letsencrypt.org.","priority":null,"port":null,"ttl":1800,"flags":0,"tag":"issue"}' \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
    https://api.digitalocean.com/v2/domains/example.com/records

For more information on how to use CAA records, see this tutorial on our community site.

Configurable TTL for Domain Records

Date: April 14, 2017

Tagged In: API v2

Author Andrew Starr-Bochicchio

Our API has been extended to support configuring the TTL value for individual domain records. This can be done when creating a new record as well as when updating an existing one via a PUT request. See the domain record documentation for further information.

Deprecating Tag Renaming

Date: March 28, 2017

Tagged In: API v2

Author Hugo Corbucci

Our API currently offers the ability to “rename” a tag by sending a PUT request to /v2/tags/$TAG_NAME. Due to low usage and operational complexities involved with its maintenance, we are deprecating this functionality. Beginning April 26th, 2017 all requests to this endpoint will respond with an HTTP status of 410 (Gone). A tag’s name also serves as its unique identifier. We’ve found that the ability to change a tag’s name introduces unneeded complexity. If you need guidance on this transition, please feel free to reach out to the team by opening a support ticket.

Tagging in Droplet create

Date: November 10, 2016

Tagged In: API v2

Author Michael Chittenden

You may now pass tags as an attribute when creating one or more new Droplets. This optional parameter will create and apply the specified tag(s) to the newly created Droplet(s). For more information see create Droplet documentation.

API v1 end-of-life

Date: November 9, 2015

Tagged In: API v1

Author Michael Chittenden

API v1 has reached end-of-life. All subsequent requests to API v1 will respond with HTTP 410 (Gone) and an error message:

# HTTP/1.1 410 (Gone)
{
  "status": "ERROR",
  "error_message": "API v1 has reached end-of-life. Please use API v2.",
  "message": "API v1 has reached end-of-life. Please use API v2."
}

Version 2 of our API provides a more RESTful interface, OAuth support, and allows access to new DigitalOcean features like Team Account Management and Floating IPs. To learn more, please visit the API documentation.

Sunsetting API v1

Date: May 1, 2015

Tagged In: API v1

Author Andrew Starr-Bochicchio

Since releasing version 2 of our API nearly a year ago and officially bringing it out of beta last month, we’ve seen a tremendous uptake of usage by our community. As the ecosystem of tools and libraries continues to grow, we’ve decided that it is time to sunset version 1 of the API.

Don’t worry! We’re not going to pull the rug out from under you. In order to give everyone time to port their tools, version 1 will not be turned off until Monday, November 9, 2015.

With its (more) RESTful interface and features like OAuth support, v2 is both powerful and easy to use. Our developer documentation should give you all the information you need to begin the transition. If you have questions, you can always ask on our Community site or on Twitter.

Sizes available

Date: March 4, 2015

Tagged In: API v2

Author Phillip Baker

Size objects now expose an available boolean attribute, which represents whether new Droplets can be created with the size.

Breaking changes in Action objects (March 20, 2015)

Date: February 20, 2015

Tagged In: API v2

Author Phillip Baker

All action objects, i.e. those returned by the /v2/actions, /v2/droplets/$ID/actions and /v2/images/$ID/actions endpoint now return a region_slug attribute, in addition to a region attribute. At 00:01 March 20, 2015 UTC, API v2 will start returning an embedded region object at the region attribute, not a slug.

For example, the API request:

curl -X GET -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582' \
    "https://api.digitalocean.com/v2/actions?page=1&per_page=1" 

would return:

{
  "actions": [
    {
      "id": 36804636,
      "status": "completed",
      "type": "create",
      "started_at": "2014-11-14T16:29:21Z",
      "completed_at": "2014-11-14T16:30:06Z",
      "resource_id": 3164444,
      "resource_type": "droplet",
      "region": {
        "name": "New York 3",
        "slug": "nyc3",
        "sizes": [
          "32gb",
          "16gb",
          "2gb",
          "1gb",
          "4gb",
          "8gb",
          "512mb",
          "64gb",
          "48gb"
        ],
        "features": [
          "virtio",
          "private_networking",
          "backups",
          "ipv6",
          "metadata"
        ],
        "available": true
      },
      "region_slug": "nyc3"
    }
  ],
  "links": {
    "pages": {
      "last": "https://api.digitalocean.com/v2/actions?page=159&per_page=1",
      "next": "https://api.digitalocean.com/v2/actions?page=2&per_page=1"
    }
  },
  "meta": {
    "total": 159
  }
}

Increase Rate Limit

Date: February 8, 2015

Tagged In: API v2

Author Phillip Baker

The maximum allowed rate limit per O-Auth token has been increased to 5,000 requests/hour.

User Image filtering

Date: January 22, 2015

Tagged In: API v2

Author Robert Ross

The images now supports a private filter which will allow you to retrieve all images that are specific to your account (IE: backups and snapshots).

For more information, you can view the documentation for this endpoint here.

New Droplet create validations

Date: January 20, 2015

Tagged In: API v2

Author Phillip Baker

API V2 now validates SSH key IDs and identifiers passed into the Droplet create call. In addition, API V2 now validates that requested features are available for a Droplet (backups, private networking, IPv6 and user data).

Add Images Filtering

Date: November 6, 2014

Tagged In: API v2

Author Robert Ross

The API v2 now supports retrieving images by type, to retrieve an image by type, simply append:

GET /v2/images?type={distribution,application}

Change type to what you would like to retrieve and voilà!

DropletKit (The Ruby API Client) also supports this functionality as well in Version 1.1.0

You can view the documentation for this feature here.

Making Sizes Clearer

Date: October 27, 2014

Tagged In: API v2

Author Aaron Lee

The JSON object for a droplet no longer contains a nested Size object, but rather a slug called size_slug that references a Size object. Please see the droplet docs for the updated structure.

The Image JSON object now includes a min_disk_size attribute that contains the slug of the minimum size droplet required for that image. For example a snapshot of a 1 Gig droplet will have “1gb” as it’s min_disk_size.

Prices are now numbers!

Date: July 25, 2014

Tagged In: API v2

Author Brooke McKim

Both price_monthly and price_hourly were previously strings. This made them harder to work with so we have gone ahead and turned them into floats.

Per Page Tweaks

Date: July 2, 2014

Tagged In: API v2

Author Brooke McKim

We have tweaked the per_page limits to default to 20 and be a maximum of 200. We have found in our testing, so far, for this to be a good balance of requests versus results. Head on over and read up on pagination.

Removed X- from RateLimit Header

Date: June 24, 2014

Tagged In: API v2

Author Brooke McKim

It seems adding X- to custom HTTP headers is going out of style.

So we gone ahead and changed our RateLimit headers to no longer include the X.

They now look like this:

RateLimit-Limit:
RateLimit-Remaining:
RateLimit-Reset: