Introduction

Welcome to the ThisDB API! You can use our API to create buckets, keys, and store information.

SDKs for Javascript and PHP are available on GitHub.

Rate Limits

The rate limit is 1,000 requests per API key per hour. Once the rate limit is reached, the server will return a HTTP 429 status code until the rate limit resets.

Keys support up to one write per second.

Global Coverage

ThisDB is an eventually consistent database system, with data cached at edge locations all around the world. This means that keys will sometimes reflect their older state until an update reaches all edge locations.

While writes will often be visible globally immediately, it can take up to 60 seconds before all edge locations are guaranteed to see the new value of a key.

Authentication

Create New API Key

Create a new API key here.

JSON Web Token (JWT) authentication is coming soon.

All requests to the V1 API must contain your API key in the X-Api-Key header.

Authorisation

Tokens

# Create a token
curl "https://api.thisdb.com/v1/tokens"
  -H "X-Api-Key: yourapikey"
  -d 'bucket=zqjvK4C908tf3mAHlcOi&prefix=user:joebloggs:&permissions=read,write&ttl=3600'

// Create a token
let headers = {
  'X-Api-Key': 'yourapikey'
}
let init = {
  headers: headers,
  method: 'POST',
  body: 'bucket=zqjvK4C908tf3mAHlcOi&prefix=user:joebloggs:&permissions=read,write&ttl=3600'
}
let response = await fetch('https://api.thisdb.com/v1/tokens', init)
let responseText = await response.text()
console.log(responseText)

// Create a token
var thisDB = new ThisDB({ apiKey: 'yourapikey' });

thisDB.createToken({ 
  bucket: 'zqjvK4C908tf3mAHlcOi', 
  prefix: 'user:joebloggs:', 
  permissions: 'read,write', 
  ttl: '3600' 
}, function(response) {
  console.log(response);
});

<?php
// Create a token
$thisDB = new \ThisDB\Client(['apiKey' => 'yourapikey']);

echo $thisDB->createToken([
  'bucket' => 'zqjvK4C908tf3mAHlcOi', 
  'prefix' => 'user:joebloggs:', 
  'permissions' => 'read,write', 
  'ttl' => '3600'
]);

The above commands outputs:

0gocgk48w0occ0c8kwk44kggwwko8c4g0g0kwgog

Your newly created token will be returned as plain text

Your API key should be treated as a secret key, and always kept on the server away from client facing applications. For client-side applications, you can generate tokens, which will provide read and/or write access to a predefined key or group of keys in a bucket.

You can give access to an individual key by specifying its full name as the prefix. However, you can also provide access to a group of keys. For example, if you want to provide access to all keys belonging to a user and you're saving keys for that user with prefix user:joebloggs:, specify the prefix as user:joebloggs:. By doing this, keys such as user:joelbloggs:emailaddress will be accessible with the token you generated.

Once you've generated a token, you can use it instead of an API key for data read/write functions.

HTTP Request

POST https://api.thisdb.com/v1/tokens

POST Parameters

Parameter	Required	Description
bucket	true	The name of the bucket you want to provide access to
prefix	true	The exact key name, or prefix of the keys you want to provide access to
permissions	true	A comma-separated list of permissions. Supports read and write
ttl	true	The time to live for this token, in seconds. The maximum is 86400

Headers

Header	Required	Description
X-Api-Key	true	Your API key

Buckets

Create New Bucket

# Create a bucket
curl -d '' "https://api.thisdb.com/v1/"
  -H "X-Api-Key: yourapikey"

// Create a bucket
let headers = {
  'X-Api-Key': 'yourapikey'
}
let init = {
  headers: headers,
  method: 'POST'
}
let response = await fetch('https://api.thisdb.com/v1/', init)
let responseText = await response.text()
console.log(responseText)

// Create a bucket
var thisDB = new ThisDB({ apiKey: 'yourapikey' });

thisDB.createBucket({}, function(response) {
  console.log(response);
});

<?php
// Create a bucket
$thisDB = new \ThisDB\Client(['apiKey' => 'yourapikey']);

echo $thisDB->createBucket();

The above commands outputs:

zqjvK4C908tf3mAHlcOi

Your newly created bucket id will be returned as plain text

This endpoint creates a new bucket.

default_ttl determines the time-to-live (ttl) for keys stored inside the bucket. Keys not updated expire after this time.

HTTP Request

POST https://api.thisdb.com/v1/

POST Parameters

Parameter	Required	Default	Description
default_ttl	false	604800	The default ttl for stored keys, in seconds. Set to 0 to disable key expiration

Headers

Header	Required	Description
X-Api-Key	true	Your API key

List All In Bucket

# List items within a bucket
curl "https://api.thisdb.com/v1/zqjvK4C908tf3mAHlcOi"
  -H "X-Api-Key: yourapikey"

// List items within a bucket
let headers = {
  'X-Api-Key': 'yourapikey'
}
let init = {
  headers: headers,
  method: 'GET'
}
let response = await fetch('https://api.thisdb.com/v1/zqjvK4C908tf3mAHlcOi', init)
let responseText = await response.text()
console.log(responseText)

// List items within a bucket
var thisDB = new ThisDB({ apiKey: 'yourapikey' });

thisDB.listBucket({ bucket: 'zqjvK4C908tf3mAHlcOi' }, function(response) {
  console.log(response);
});

<?php
// List items within a bucket
$thisDB = new \ThisDB\Client(['apiKey' => 'yourapikey']);

echo $thisDB->listBucket(['bucket' => 'zqjvK4C908tf3mAHlcOi']);

The above returns a list of items in the bucket:

hello
another
foo

This endpoint lists all items stored within a bucket.

HTTP Request

GET https://api.thisdb.com/v1/<BUCKETID>

URL Parameters

Parameter	Required	Default	Description
limit	false	1000	Limit the number of rows returned. Maximum value is 1000
values	false	false	Returns the value of each key if true
format	false	text	The format to return data in. Can be text, json, ndjson

Headers

Header	Required	Description
X-Api-Key	true	Your API key

Update a Bucket

Update a bucket with the following code

curl "https://api.thisdb.com/v1/zqjvK4C908tf3mAHlcOi"
  -XPATCH
  -H "X-Api-Key: yourapikey"
  -d 'default_ttl=3600'

let headers = {
  'X-Api-Key': 'yourapikey'
}
let init = {
  headers: headers,
  method: 'PATCH'
  body: 'default_ttl=3600'
}
let response = await fetch('https://api.thisdb.com/v1/zqjvK4C908tf3mAHlcOi', init)
let responseText = await response.text()
console.log(responseText)

var thisDB = new ThisDB({ apiKey: 'yourapikey' });

thisDB.updateBucket({ bucket: 'zqjvK4C908tf3mAHlcOi', ttl: '3600' }, function(response) {
  console.log(response);
});

<?php
$thisDB = new \ThisDB\Client(['apiKey' => 'yourapikey']);

echo $thisDB->updateBucket(['bucket' => 'zqjvK4C908tf3mAHlcOi', 'ttl' => '3600']);

The above will return OK, if successful

OK

This endpoint updates an existing bucket.

HTTP Request

PATCH https://api.thisdb.com/v1/<BUCKETID>

PATCH Parameters

Parameter	Required	Default	Description
default_ttl	false	604800	The default ttl for stored data, in seconds

Headers

Header	Required	Description
X-Api-Key	true	Your API key

Delete a Bucket

To delete a bucket, use this code:

curl "https://api.thisdb.com/v1/zqjvK4C908tf3mAHlcOi"
  -H "X-Api-Key: yourapikey"
  -XDELETE

let headers = {
  'X-Api-Key': 'yourapikey'
}
let init = {
  headers: headers,
  method: 'DELETE'
}
let response = await fetch('https://api.thisdb.com/v1/zqjvK4C908tf3mAHlcOi', init)
let responseText = await response.text()
console.log(responseText)

var thisDB = new ThisDB({ apiKey: 'yourapikey' });

thisDB.deleteBucket({ bucket: 'zqjvK4C908tf3mAHlcOi' }, function(response) {
  console.log(response);
});

<?php
$thisDB = new \ThisDB\Client(['apiKey' => 'yourapikey']);

echo $thisDB->deleteBucket(['bucket' => 'zqjvK4C908tf3mAHlcOi']);

The above will return 'OK' if successful

OK

This endpoint deletes a specific bucket.

HTTP Request

DELETE https://api.thisdb.com/v1/<BUCKETID>

Headers

Header	Required	Description
X-Api-Key	true	Your API key

Keys

Get a Key Value

To get a key contained within a bucket, use this code:

curl "https://api.thisdb.com/v1/zqjvK4C908tf3mAHlcOi/foo"
  -H "X-Api-Key: yourapikey"

let headers = {
  'X-Api-Key': 'yourapikey'
}
let init = {
  headers: headers,
  method: 'GET'
}
let response = await fetch('https://api.thisdb.com/v1/zqjvK4C908tf3mAHlcOi/foo', init)
let responseText = await response.text()
console.log(responseText)

var thisDB = new ThisDB({ apiKey: 'yourapikey' });

thisDB.get({ bucket: 'zqjvK4C908tf3mAHlcOi', key: 'foo' }, function(response) {
  console.log(response);
});

<?php
$thisDB = new \ThisDB\Client(['apiKey' => 'yourapikey']);

echo $thisDB->get(['bucket' => 'zqjvK4C908tf3mAHlcOi', 'key' => 'foo']);

The above will return the key's value:

bar

This endpoint returns a key value.

HTTP Request

GET https://api.thisdb.com/v1/<BUCKETID>/<KEYNAME>

URL Parameters

Parameter	Required	Default	Description
format	false	text	The format to return data in. Can be text, json, ndjson

Headers

Header	Required	Description
X-Api-Key	true	Your API key. An API key OR token is required
X-Token	true	Your token. A token OR API key is required

Set a Key Value

# Set a key
curl "https://api.thisdb.com/v1/zqjvK4C908tf3mAHlcOi/foo"
  -H "X-Api-Key: yourapikey"
  -d 'bar'

# Set a key with an hour expiry
curl "https://api.thisdb.com/v1/zqjvK4C908tf3mAHlcOi/foo?ttl=3600"
  -H "X-Api-Key: yourapikey"
  -d 'bar'

// Get a key
let headers = {
  'X-Api-Key': 'yourapikey'
}
let init = {
  headers: headers,
  method: 'POST'
  body: 'bar'
}
let response = await fetch('https://api.thisdb.com/v1/zqjvK4C908tf3mAHlcOi/foo', init)
let responseText = await response.text()
console.log(responseText)

// Set a key with an hour expiry
let headers = {
  'X-Api-Key': 'yourapikey'
}
let init = {
  headers: headers,
  method: 'POST'
  body: 'bar'
}
let response = await fetch('https://api.thisdb.com/v1/zqjvK4C908tf3mAHlcOi/foo?ttl=3600', init)
let responseText = await response.text()
console.log(responseText)

var thisDB = new ThisDB({ apiKey: 'yourapikey' });

thisDB.set({
  bucket: 'zqjvK4C908tf3mAHlcOi', 
  key: 'foo', 
  value: 'bar'
}, function(response) {
  console.log(response);
});

<?php
$thisDB = new \ThisDB\Client(['apiKey' => 'yourapikey']);

echo $thisDB->set([
  'bucket' => 'zqjvK4C908tf3mAHlcOi', 
  'key' => 'foo', 
  'value' => 'bar'
]);

The above will return 'OK' if successful

OK

This endpoint sets a key value.

HTTP Request

POST https://api.thisdb.com/v1/<BUCKETID>/<KEYNAME>

URL Parameters

Parameter	Required	Default	Description
ttl	false	the bucket's default ttl	The time to live for this key, in seconds. The default is the bucket's default ttl

Headers

Header	Required	Description
X-Api-Key	true	Your API key. An API key OR token is required
X-Token	true	Your token. A token OR API key is required

Increment a Key Value

Increment or decrement a key with the following code:

curl "https://api.thisdb.com/v1/zqjvK4C908tf3mAHlcOi/foo"
  -H "X-Api-Key: yourapikey"
  -XPATCH
  -d '+1'

let headers = {
  'X-Api-Key': 'yourapikey'
}
let init = {
  headers: headers,
  method: 'PATCH',
  body: '+1'
}
let response = await fetch('https://api.thisdb.com/v1/zqjvK4C908tf3mAHlcOi/foo', init)
let responseText = await response.text()
console.log(responseText)

var thisDB = new ThisDB({ apiKey: 'yourapikey' });

thisDB.increment({ 
  bucket: 'zqjvK4C908tf3mAHlcOi', 
  key: 'foo', 
  value: '+1'
}, function(response) {
  console.log(response);
});

<?php
$thisDB = new \ThisDB\Client(['apiKey' => 'yourapikey']);

echo $thisDB->increment([
  'bucket' => 'zqjvK4C908tf3mAHlcOi', 
  'key' => 'foo', 
  'value' => '+1'
]);

The above will return the new value of the key, if successful

2

This endpoint increments or decrements a key value

HTTP Request

PATCH https://api.thisdb.com/v1/<BUCKETID>/<KEYNAME>

To increment a key, use +1.

To decrement a key, use -1.

Headers

Header	Required	Description
X-Api-Key	true	Your API key. An API key OR token is required
X-Token	true	Your token. A token OR API key is required

Delete a Key Value

Delete a key with the following code:

curl "https://api.thisdb.com/v1/zqjvK4C908tf3mAHlcOi/foo"
  -H "X-Api-Key: yourapikey"
  -XDELETE

let headers = {
  'X-Api-Key': 'yourapikey'
}
let init = {
  headers: headers,
  method: 'DELETE'
}
let response = await fetch('https://api.thisdb.com/v1/zqjvK4C908tf3mAHlcOi/foo', init)
let responseText = await response.text()
console.log(responseText)

var thisDB = new ThisDB({ apiKey: 'yourapikey' });

thisDB.delete({ bucket: 'zqjvK4C908tf3mAHlcOi', key: 'foo' }, function(response) {
  console.log(response);
});

<?php
$thisDB = new \ThisDB\Client(['apiKey' => 'yourapikey']);

echo $thisDB->delete(['bucket' => 'zqjvK4C908tf3mAHlcOi', 'key' => 'foo']);

The above will return OK, if successful

OK

This endpoint deletes a key value

HTTP Request

DELETE https://api.thisdb.com/v1/<BUCKETID>/<KEYNAME>

Headers

Header	Required	Description
X-Api-Key	true	Your API key. An API key OR token is required
X-Token	true	Your token. A token OR API key is required

Status Codes

ThisDB API can return the following status codes:

Code	Meaning
200	OK - Your request was successful.
400	Bad Request - Your request is invalid.
403	Forbidden - Your API key is wrong.
404	Not Found - The resource you were looking for could not be found.
405	Method Not Allowed - You tried to access a method that isn't valid.
406	Not Acceptable - You requested a format that isn't supported.
429	Too Many Requests - The rate limit has been reached.
500	Internal Server Error - The was a problem processing your request.
503	Service Unavailable - We're temporarily offline for maintenance. Please try again later.