Api v2 Changelog

SOA records are now returned in record results, and you can update the TTL on a SOA record as you would with other records. This allows you to control the negative caching of your domain. SOA records cannot be manually deleted or created on a domain, they are created when the domain is created, and cleaned up on the domain deletion.

Today, we are promoting the Kubernetes API to General Availability. As part of this release, we have also extended the API with additional functionality:

When creating or updating a cluster, you may now configure a maintenance window policy specifying the day of the week and time of day that updates should take place for the cluster. Additionally, setting a cluster’s auto_upgrade attribute to true will specify that the cluster can be automatically upgraded to new Kubernetes patch releases (e.g. 1.13.1 to 1.13.2) during its maintenance window.

An upgrade endpoint is now available to imminently trigger an upgrade to a newer patch release of Kubernetes at your own convienience. You may list available upgrades for your cluster using the upgrades endpoint.

In order to give users finer control over individual nodes, the recycle endpoint has been deprecated. Instead, we now offer the ability to delete or replace specific nodes in a node pool. By default, workloads will be drained from the node before deletion. Appending the skip_drain=1 query parameter to the request will cause the node to be imminently deleted. Appending the replace=1 query parameter to the request will cause the node to be replaced by a new one after it has been deleted.

For the full details, see the API reference documentation for Kubernetes.

The /v2/volumes/$volume_id/snapshots endpoint now accepts tags at creation time, and these are reflected on the /v2/snapshots endpoint. Volume snapshot tags may now be managed with the /v2/tags endpoint as well. For more information, see the API reference documentation for both block storage volumes and tags.

Spaces, DigitalOcean’s object storage solution, includes a built-in CDN. Today we’ve added the ability to use custom subdomains with your CDN endpoints. When configuring your CDN via the API, you can now set the custom_domain attribute to use a subdomain with the endpoint. When a custom subdomain is in use, the certificate_id attribute is also required. Its value must be the the ID of a DigitalOcean managed SSL certificate. For example, the body of your request to enable a CDN might look like:

DigitalOcean Load Balancers now support using PROXY Protocol to pass information like origin IP addresses and port numbers from connecting client requests along to the backend service. This can be configured using the API by setting the new enable_proxy_protocol attribute to true when creating a new Load Balancer or updating an existing one.

As announced on September 5, 2018, the last_tagged attribute returned in response to GET requests to the /v2/tags or /v2/tags/$TAG_NAME endpoints has been deprecated. Beginning March 1st, 2019, last_tagged will no longer be populated in favor of the last_tagged_uri attribute.

For example, a GET request to /v2/tags/frontend currently might return:

Today DigitalOcean’s Managed Database service, including its API, has entered Limited Availability. In order to access these new endpoints, you must first enable Managed Databases on your account by opting-in via the cloud control panel. Once enabled, you will be able to create, scale, and manage your database clusters via the API. For example, to create a new database cluster, make a POST to the /v2/databases endpoint with a JSON body like:

The response will include a full JSON representation of the database cluster. The initial value of the cluster’s status attribute will be “creating.” When the cluster is ready for use, this will transition to “online.”

The /v2/volumes endpoint now displays tags and supports adding them to volumes at creation time. Volume tags may now be managed with the /v2/tags endpoint as well. For more information, see the API reference documentation for both block storage volumes and tags.

Once enabled, you will be able to list, create, or delete clusters as well as scale node pools up and down, recycle individual nodes, and retrieve the kubeconfig file for use with a cluster via the API. For example, to create a new cluster with a node pool using three s-2vcpu-2gb Droplets, make a POST to the /v2/kubernetes/clusters endpoint with a JSON body like:

The response will include a full JSON representation of the cluster. The initial value of the cluster’s status.state attribute will be “provisioning.” When the cluster is ready for use, this will transition to “running.” You can use the /v2/kubernetes/options endpoint to find the available versions of Kubernetes as well as the supported regions and Droplet sizes.

Once ready, you can retrieve the credentials for use with the cluster by sending a GET request to /v2/kubernetes/clusters/$K8S_CLUSTER_ID/kubeconfig. The response will be a kubeconfig file in yaml format. This file can be used to connect to and administer the cluster using the Kubernetes command line tool, kubectl. For more information, see “How to Connect to a DigitalOcean Kubernetes Cluster with kubectl.”

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:

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.

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:

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.

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:

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.

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, 2019last_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.

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:

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:

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.

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:

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.

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.

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:

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.

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.

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.

The Image action endpoint now responds to a convert attribute, that allows backups and temporary snapshots to be saved permanently as snapshots. For more information, see the image actions documentation.

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.

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).

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.

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.