An Introduction to the DigitalOcean Products API

The DigitalOcean API lets you manage Droplets and other DigitalOcean resources in a programmatic way using conventional HTTP requests. The endpoints let you retrieve information or execute actions. All of the functionality in the DigitalOcean Control Panel is also available through the API.

This document explains HTTP request methods and return statuses, the structure of the response body, rate limiting, and OAuth authentication.

Requests

Any tool that can use HTTP can communicate with the API by requesting the correct URI. You should make requests using the HTTPS protocol so that traffic is encrypted. The interface responds to different methods depending on the action required.

HTTP Statuses

The API returns standard HTTP statuses, including error codes. In the event of a problem, the status contains the error code and the body of the response usually contains additional information about the problem.

Here are some guidelines for interpreting status codes:

• A status code in the 200 range indicates that a request was fulfilled successfully.

• A status code in the 400 range indicate that there was an issue with the request. This could mean that you did not authenticate correctly, that you are requesting an action that you do not have authorization for, that the object you are requesting does not exist, or that your request is malformed.

• A status code in the 500 range indicates a server-side problem. This means that there is an issue with our API and it cannot fulfill your request currently.

400- and 500-level error responses include a JSON object in their body, including the following attributes:

Here is an example error response:

HTTP/1.1 403 Forbidden
{
    "id":       "forbidden",
    "message":  "You do not have access for the attempted action."
}

Responses

When a request is successful, a response body is typically sent back in the form of a JSON object. An exception to this is when a DELETE request is processed, which results in a successful HTTP 204 status and an empty response body.

Inside of this JSON object, the resource root that was the target of the request is set as the key. This is the singular form of the word if the request operated on a single object, and the plural form of the word if a collection was processed.

For example, if you send a GET request to /v2/droplets/$DROPLET_ID you get back an object with a key called “droplet”. However, if you send the GET request to the general collection at /v2/droplets, you get back an object with a key called “droplets”.

The value of these keys is generally a JSON object for a request on a single object and an array of objects for a request on a collection of objects.

This is a truncated example response for a single object:

{
    "droplet": {
        "name": "example.com"
    }
}

This is a truncated example response for an object collection:

{
    "droplets": [
        {
            "name": "example.com"
        },
        {
            "name": "second.com"
        }
    ]
}

Meta

In addition to the main resource root, the response may also contain a meta object. This object contains information about the response itself.

The meta object contains a total key that is set to the total number of objects returned by the request. This has implications on the links object and pagination.

The meta object is only displayed when it has a value. Currently, the meta object has a value when a request is made on a collection (like droplets or domains).

Here is an example meta object:

{
    "meta": {
        "total": 43
    }
}

Links & Pagination

The links object is returned as part of the response body when pagination is enabled. By default, 20 objects are returned per page. If the response contains 20 objects or fewer, no links object is returned. If the response contains more than 20 objects, the first 20 are returned along with the links object.

You can request a different pagination limit or force pagination by appending ?per_page= to the request with the number of items you would like per page. For instance, to show only two results per page, you could add ?per_page=2 to the end of your query. The maximum number of results per page is 200.

The links object contains a pages object. The pages object, in turn, contains keys indicating the relationship of additional pages. The values of these are the URLs of the associated pages. The keys are one of the following:

• first: The URI of the first page of results.
• prev: The URI of the previous sequential page of results.
• next: The URI of the next sequential page of results.
• last: The URI of the last page of results.

The pages object only includes the links that make sense. So for the first page of results, no first or prev links are ever set. This convention holds true in other situations where a link would not make sense.

Here is an example links object:

{
    "links": {
        "pages": {
            "last": "https://api.digitalocean.com/v2/images?page=2",
            "next": "https://api.digitalocean.com/v2/images?page=2"
        }
    }
}

Rate Limit

Requests through the API are rate limited per OAuth token. Current rate limits:

• 5,000 requests per hour
• 250 requests per minute (5% of the hourly total)

Once you exceed either limit, you are rate limited until the next cycle starts. Space out any requests that you would otherwise issue in bursts for the best results.

The rate limiting information is contained within the response headers of each request. The relevant headers are:

• RateLimit-Limit: The number of requests that can be made per hour.
• RateLimit-Remaining: The number of requests that remain before you hit your request limit. See the information below for how the request limits expire.
• RateLimit-Reset: This represents the time when the oldest request expires. The value is given in Unix epoch time. See below for more information about how request limits expire.

As long as the RateLimit-Remaining count is above zero, you are able to make additional requests.

The way that a request expires and is removed from the current limit count is important to understand. Rather than counting all of the requests for an hour and resetting the RateLimit-Remaining value at the end of the hour, each request instead has its own timer.

This means that each request contributes toward the RateLimit-Remaining count for one complete hour after the request is made. When that request’s timer runs out, it is no longer counted towards the request limit.

This has implications on the meaning of the RateLimit-Reset header as well. Because the entire rate limit is not reset at one time, the value of this header is set to the time when the oldest request expires. This is why you may see your RateLimit-Reset value change, but not move an entire hour into the future.

If the RateLimit-Remaining reaches zero, subsequent requests receive a 429 error code until the request reset has been reached. You can see the format of the response in the examples.

The following endpoints have special rate limit requirements that are independent of the limits defined above.

• Only 12 POST requests to the /v2/reserved_ips endpoint to create Reserved IPs can be made per 60 seconds.
• Only 10 GET requests to the /v2/account/keys endpoint to list SSH keys can be made per 60 seconds.

Here is an example of rate limit headers:

RateLimit-Limit: 1200
RateLimit-Remaining: 1193
RateLimit-Reset: 1402425459

Here is an example of a rate exceeded response:

429 Too Many Requests
{
    id: "too_many_requests",
    message: "API Rate limit exceeded."
}

Curl Examples

Throughout the API documentation, we show some example API requests that use the curl command to demonstrate the various endpoints in a readable, textual format.

The names of account-specific references (like Droplet IDs) are represented by variables. For instance, a Droplet ID may be represented by a variable called $DROPLET_ID. You can set the associated variables in your environment if you wish to use the examples without modification.

The first variable that you should set to get started is your OAuth authorization token:

How to Create a Personal Access Token

Create a personal access token for use with the DigitalOcean API.

Generate a token by going to the Apps & API section of the DigitalOcean Control Panel. Use an existing token if you have saved one, or generate a new token with the “Generate new token” button.

After you generate the token, you can export the TOKEN variable in your environment.

You may also wish to set some other variables now or as you go along. For example, you may wish to set the DROPLET_ID variable to one of your Droplet IDs since this is used frequently in the API.

If you need access to the headers of a response through curl, you can pass the -i flag to display the header information along with the body. If you are only interested in the header, you can instead pass the -I flag, which excludes the response body entirely.

To set and export your OAuth token:

export TOKEN=your_token_here

To set and export a variable:

export DROPLET_ID=1111111

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account in full or in read-only mode.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean Control Panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. Upon generation, the web interface only displays each token once in order to prevent the token from being compromised.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Here is the command to authenticate with a bearer authorization header:

curl -X $HTTP_METHOD -H "Authorization: Bearer $TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

Parameters

There are two different ways to pass parameters in a request with the API.

When passing parameters to create or update an object, parameters should be passed as a JSON object containing the appropriate attribute names and values as key-value pairs. When you use this format, you should specify that you are sending a JSON object in the header. This is done by setting the Content-Type header to application/json. This ensures that your request is interpreted correctly.

When passing parameters to filter a response on GET requests, parameters can be passed using standard query attributes. In this case, the parameters would be embedded into the URI itself by appending a ? to the end of the URI and then setting each attribute with an equal sign. Attributes can be separated with a &. Tools like curl can create the appropriate URI when given parameters and values; this can also be done using the -F flag and then passing the key and value as an argument. The argument should take the form of a quoted string with the attribute being set to a value with an equal sign.

Here is an example of passing parameters as a JSON object:

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

Here is an example of filtering parameters as a query string:

curl -H "Authorization: Bearer $TOKEN" \
    -X GET \
    "https://api.digitalocean.com/v2/images?private=true"

Cross Origin Resource Sharing

To make requests to the API from other domains, the API supports Cross Origin Resource Sharing (CORS).

CORS is generally used to create AJAX requests outside of the originating request’s domain. This is necessary to implement projects like control panels using the API. This tells the browser that it can send requests to an outside domain.

The procedure that the browser initiates in order to perform these actions (other than GET requests) begins by sending a preflight request. This sets the Origin header and uses the OPTIONS method. The server replies back with the methods it allows and some of the limits it imposes. The client then sends the actual request if it falls within the allowed constraints.

This process is usually done in the background by the browser, but you can use curl to emulate this process using the example provided. The headers that are set to show the constraints are:

• Access-Control-Allow-Origin: This is the domain that is sent by the client or browser as the origin of the request. It is set through an Origin header.
• Access-Control-Allow-Methods: This specifies the allowed options for requests from that domain. This generally is all available methods.
• Access-Control-Expose-Headers: This contains the headers that are available to requests from the origin domain.
• Access-Control-Max-Age: This is the length of time that the access is considered valid. After this expires, a new preflight should be sent.
• Access-Control-Allow-Credentials: This is set to true. It basically allows you to send your OAuth token for authentication.

The browser typically handles the details of these headers, so you don’t need to manually interact with them.