Create New Database – POST /api/databases

This call creates a new database asynchronously, billed to the default credit card associated with your account in the web console.

The database will be ready within a few minutes after the call successfully completes. You can check the build status with the Get Database Information API call, or just try to log in to the returned database hostname until it's ready. (Please don't hammer the server! Have your code sleep for at least 30 seconds between retry attempts.)

Request

The POST parameters specify what kind of server you wish to provision.

Required parameters

Only one parameter is required: size tells the server what memory size you want your database to have. The exact set of sizes available may (rarely) change depending on datacenter availability. The currently valid list of sizes can be obtained from the /api/plans API call. As of this writing, the available sizes are

{"512mb", "1gb", "2gb", "4gb", "8gb", "16gb", "48gb", "64gb"}

Optional parameters

• region — the datacenter region where you want to run your server.

  The default is nyc3 if no region is given. As of this writing, the available regions are:

  {"nyc3", "nyc2", "sfo1", "ams2", "ams3", "lon1", "sgp1", "fra1"}

  These correspond to New York, San Francisco, Amsterdam, London, Singapore, and Frankfurt.

  Regions are rarely added or removed depending on datacenter availability; the /api/plans API call provides current information on what is available.

Reply

The HTTP status code of the reply tells you whether your request worked. Additional information is in the reply body. The possible status codes are:

• 202 Accepted — The request succeded, and your database is now being built. The reply body contains the hostname and superuser password. Call the Get Database Information API call in a few minutes to check on the build status. (Please do not hammer the server! Have your code sleep for at least 30 seconds between calls.)

  An example 202 reply body:

  {
    "hostname": "foo-bar-123.db.databaselabs.io",
    "id": "65f76f7d-16c8-4dab-97a0-245e15a2556c",
    "password": "xMG0PuSeKmf8bmzKl", 
    "status": "building"
   }

• 400 Bad Request — The server could not process your request. This could be because the POST body is not a map in JSON format, or because it's missing the required size key. Check the reply body for details.
• 401 Unauthorized — Your API key or API secret were invalid. Check your credentials and try again. Case matters!
• 402 Payment Required — Your default credit card could not be billed. Check that your credit card is valid in the web console and try again.

Example

% http -a $MY_API_CREDENTIALS https://www.databaselabs.io/api/databases size=512mb


      HTTP/1.1 202 Accepted
      Content-Length: 140
      Content-Type: application/json
      Date: Wed, 20 Aug 2014 23:05:09 GMT
      Server: http-kit
      Vary: Accept

      {
      "hostname": "foo-bar-123.db.databaselabs.io", 
      "id": "65f76f7d-16c8-4dab-97a0-245e15a2556c", 
      "password": "xMG0PuSeKmf8bmzKl", 
      "status": "building"
      }

☝ Back to Top

List All Databases – GET /api/databases

This call lists all active databases associated with your account.

Reply

A JSON array of your active databases is returned in the body. Each array element is a hashmap of information about one database, as in the example below.

The database status codes in the result body are described in the database status codes section above.

HTTP status codes are used as follows:

• 200 OK — Success; returning a list of your databases.
• 401 Unauthorized — Your API key or API secret were invalid. Check your credentials and try again. Case matters!

Example

% http -a $MY_API_CREDENTIALS https://www.databaselabs.io/api/databases



      HTTP/1.1 200 Accepted
      Content-Length: 692
      Content-Type: application/json
      Date: Wed, 20 Aug 2014 23:05:09 GMT
      Server: http-kit
      Vary: Accept

[
    {
        "hostname": "vivid-answer-395.db.databaselabs.io", 
        "hostsize": "512mb", 
        "id": "65f76f7d-16c8-4dab-97a0-245e15a2556c", 
        "region": "nyc2", 
        "status": "ready", 
        "updated-at": "2014-08-20T03:05:09.678Z", 
        "cloud": "digitalocean"
    }, 
    {
        "hostname": "adept-star-277.db.databaselabs.io", 
        "hostsize": "512mb", 
        "id": "cb222fb7-1fcd-49bd-89f1-a86bb98b8119", 
        "region": "nyc2", 
        "status": "ready", 
        "updated-at": "2014-08-20T03:11:47.436Z", 
        "cloud": "digitalocean"
    }, 
    {
        "hostname": "classic-rhinoceros-521.db.databaselabs.io", 
        "hostsize": "512mb", 
        "id": "ad1d60b1-5ba2-4472-a718-e86d4327f851", 
        "region": "nyc2", 
        "status": "ordered", 
        "updated-at": "2014-08-20T03:29:50.006Z", 
        "cloud": "digitalocean"
    }
]

☝ Back to Top

Get Database Information – GET /api/databases/{hostname}

This call returns status information about a specific database hostname. Replace {hostname} with the database hostname you're interested in.

Reply

A 200 status and a JSON hashmap of information about the host is returned upon success. A 404 status is returned if the requested hostname doesn't exist. The database status codes in the result body are described in the database status codes section above.

The database status codes in the result body are described in the database status codes section above.

HTTP status codes are used as follows:

• 200 OK — Success; returning a list of your databases.
• 404 Not Found — The requested hostname doesn't exist.
• 401 Unauthorized — Your API key or API secret were invalid. Check your credentials and try again. Case matters!

Example

% http -a $MY_API_CREDENTIALS \
https://www.databaselabs.io/api/databases/classic-rhinoceros-521.db.databaselabs.io



      HTTP/1.1 200 Accepted
      Content-Length: 234
      Content-Type: application/json
      Date: Wed, 20 Aug 2014 23:05:09 GMT
      Server: http-kit
      Vary: Accept

    {
        "hostname": "classic-rhinoceros-521.db.databaselabs.io", 
        "hostsize": "512mb", 
        "id": "ad1d60b1-5ba2-4472-a718-e86d4327f851", 
        "region": "nyc2", 
        "status": "ordered", 
        "updated-at": "2014-08-20T03:29:50.006Z", 
        "cloud": "digitalocean"
    }

☝ Back to Top

Delete Database – DELETE /api/databases/{hostname}

This call asynchronously destroys the given database. Replace {hostname} with the database hostname you want to delete.

Reply

HTTP status codes are used as follows:

• 204 No Content — Success; your DELETE request has been enqueued. The database will be destroyed within a few minutes.
• 404 Not Found — The requested hostname doesn't exist.
• 401 Unauthorized — Your API key or API secret were invalid. Check your credentials and try again. Case matters!

Example

% http -a $MY_API_CREDENTIALS \
DELETE https://www.databaselabs.io/api/databases/classic-rhinoceros-521.db.databaselabs.io



      HTTP/1.1 204 No Content
      Content-Length: 0
      Content-Type: text/plain
      Date: Wed, 20 Aug 2014 23:05:09 GMT
      Server: http-kit

☝ Back to Top

List Plans – GET /api/plans

This call tells you what datacenters, server sizes, and SLAs are currently available. These can change from time to time as new datacenter capacity is added or old capacity becomes exhausted.

The reply is an array of maps. Each map has the following keys:

• id – Unique subscription plan ID code, such as 512mb-do-ams3-dev
• hostsize – amount of server memory (RAM)
• region – Region identifier code, such as ams3
• cloud – The cloud where the database is hosted. Valid values are "google", "digitalocean", or "aws".

Reply

HTTP status codes are used as follows:

• 200 OK — Success.
• 401 Unauthorized — Your API key or API secret were invalid. Check your credentials and try again. Case matters!

Example

% http -a $MY_API_CREDENTIALS  https://www.databaselabs.io/api/clouds


HTTP/1.1 200 OK
Content-Length: 135
Content-Type: application/json;charset=UTF-8
Date: Wed, 20 Jan 2015 23:20:50 GMT
Server: http-kit
Vary: Accept

[
    {
        "hostsize": "512mb", 
        "id": "512mb-do-ams3-dev", 
        "monthly_price_dollars": 20,
        "region": "ams3", 
        "region_description": "Amsterdam 3", 
        "cloud": "digitalocean"
    }, 
    {
        "hostsize": "512mb", 
        "id": "512mb-do-nyc3-dev", 
        "monthly_price_dollars": 20, 
        "region": "nyc3", 
        "region_description": "New York 3", 
        "cloud": "digitalocean"
    }, 
    {
        "hostsize": "512mb", 
        "id": "512mb-do-lon1-dev", 
        "monthly_price_dollars": 20, 
        "region": "lon1", 
        "region_description": "London 1", 
        "cloud": "digitalocean"
  },
  [etc...]
]

☝ Back to Top