Introduction
Welcome to the KVdb API! You can use our simple REST API to store arbitrary key-value pairs, which can contain any type of data, such as text, numbers, counters, and binary data. Depending on the data type, the API offers additional features to make collecting and accessing data easier.
While all the examples are currently given in Shell script (using curl on the command line), more formats will be added soon.
Authentication
To authorize, use this code:
# Provide the key as the username using HTTP Basic authentication
curl https://kvdb.io/BUCKET/KEY
-u 'mykey:'
# Or in the query string
curl https://kvdb.io/BUCKET/KEY?key=mykey
While not all API endpoints require the use of an API key, should you choose to use one, use the key in the username field when sending HTTP Basic authentication credentials.
Alternatively, you may specify the key in the key
query string parameter.
Rate Limits
The rate limit is 1,000 requests per IP address per hour. Refer to the X-Ratelimit-Limit
, X-Ratelimit-Remaining
, and X-Ratelimit-Reset
response headers to know when you are approaching the limit. Once the rate limit is reached, the server will return a HTTP 429 status code until the rate limit resets.
For customers on a paid plan, please contact us to increase rate limits. This is so we can do capacity planning accordingly.
Buckets
A bucket is a collection of keys. The keys in a bucket share the same access keys, expiration (TTL) setting, and other bucket policy. Depending on your application, you may use one bucket for all your keys, or segregate keys based on users, groups, or other categorization in your application.
You may create bucket-specific access keys:
Key | Default | Set this to... |
---|---|---|
secret_key | None | Prevent listing keys, update bucket policy |
write_key | None | Write-protect the bucket |
In addition, you may configure the following bucket policies:
Setting | Default | Meaning |
---|---|---|
default_ttl | 604800 (1 week) | Keys not updated expire after this time (seconds) |
Create a Bucket
# Create a new bucket that lets anyone read, write, and list keys
curl -d '' https://kvdb.io
The above command returns the bucket id as plain text:
N7cmQg1DwZbADh2Hu3NncF
# Create a new bucket with a secret_key, write_key,
# and set all keys to expire after 1 hour
curl https://kvdb.io \
-d 'secret_key=supersecret' \
-d 'write_key=knock' \
-d 'default_ttl=3600'
Our API will generate a bucket id for you to use. Make sure to set a secret_key
to protect the bucket. It is not possible to add a secret_key
to a bucket after creation, however, it is possible to change it.
There is no API to list publicly-accessible buckets, so using a bucket without an access key is safe as long as the bucket id isn't made public. We only recommend these kinds of buckets for testing purposes.
Update Bucket Policy
# Make bucket read-only
curl https://kvdb.io/N7cmQg1DwZbADh2Hu3NncF \
-d 'write_key=knock' \
-u 'supersecret:' \
-XPATCH
If a bucket has a secret_key
set, you may update its policy (and the secret_key
itself).
List Keys
# List keys
curl https://kvdb.io/N7cmQg1DwZbADh2Hu3NncF/ \
-u 'supersecret:'
# List keys with the prefix hits_2018
# Regular expression: ^hits_2018.* (URL encode it)
curl 'https://kvdb.io/N7cmQg1DwZbADh2Hu3NncF/?regex=%5Ehits_2018.*' \
-u 'supersecret:'
# List keys and their values as JSON
curl 'https://kvdb.io/N7cmQg1DwZbADh2Hu3NncF/?values=true&format=json' \
-u 'supersecret:'
This would return an array of JSON arrays with key-value pairs:
[
["visitors", 101],
["flavor-today", "coconut"]
]
Listing keys in a bucket is simple. If the bucket is protected by a secret_key
, be sure to provide it.
The following query string paramateres can be used to influence the output:
Parameter | Default | Meaning |
---|---|---|
limit | 10000 | Maximum number of keys to return |
regex | .* |
Only return keys matching regular expression |
values | false | Return values |
format | Accept header | Change the output format (see below) |
The HTTP Accept
header is used to determine the output if the format
parameter is not specified. If no specific header is sent, text
is assumed.
The following formats are supported:
Format | Without Values | With Values | Value Escaping |
---|---|---|---|
text | key |
key=value |
Newline: \n |
json | ["key"] |
[["key", value]] |
None |
jsonl | "key" |
["key", value] |
None |
jsonl
is newline-delimited JSON, a format easy to process with command-line and other tools expecting one JSON object per line. It must be specifically requested with a ?format=jsonl
query string.
Delete Bucket
# Delete bucket
curl https://kvdb.io/N7cmQg1DwZbADh2Hu3NncF/ \
-XDELETE
-u 'supersecret:'
Use this to delete a bucket and all of its keys. For large buckets, this operation may not complete immediately, even though a successful response is returned by the API.
Keys
Key names can be of arbitrary composition (even binary data), but are limited to 128 bytes in length. Values can be of any data type but are limited to 16 KB in size. Numeric values are detected automatically and are enforced by the API.
Set a Key Value
# Set key
curl https://kvdb.io/N7cmQg1DwZbADh2Hu3NncF/hello \
-d 'world'
# Set key with a 30 second expiry
curl https://kvdb.io/N7cmQg1DwZbADh2Hu3NncF/hello?ttl=30 \
-d 'world'
The maximum length of a key is 128 bytes.
To override the bucket's default key expiration, use the ttl
query parameter to specify the TTL for this key.
Get a Key Value
# Get value
curl https://kvdb.io/N7cmQg1DwZbADh2Hu3NncF/hello
The response is the value:
world
Update a Key (Counter)
# Increment counter by 1
curl https://kvdb.io/N7cmQg1DwZbADh2Hu3NncF/visits
-d '+1'
-XPATCH
The API responds with the new value of the counter:
1
To store counters, the server will detect integer (64-bit signed) and floating point (64-bit) values and store them efficiently, to allow incrementing and decrementing them. Use the PATCH
HTTP method to operate on a value this way. If the key does not exist, it is created and assumed to be zero before the operation.
To increment the value, use +
.
To decrement the value, use -
.
You can also use the ttl
query parameter to set the TTL for this key.
Delete a Key
# Delete key
curl https://kvdb.io/N7cmQg1DwZbADh2Hu3NncF/hello \
-XDELETE
If you need to delete a key before it expires, use this method.
Errors
The API uses the following error codes:
Error Code | Meaning |
---|---|
400 | Bad Request -- Your request is invalid. |
401 | Unauthorized -- Your API key is wrong. |
403 | Forbidden -- Bucket policy blocked the request. |
404 | Not Found -- The specified key could not be found. |
405 | Method Not Allowed -- You tried to access a bucket or key with an invalid method. |
406 | Not Acceptable -- You requested an unsupported output format. |
410 | Gone -- The requested resource has been removed from our servers. |
418 | I'm a teapot. |
429 | Too Many Requests -- You're making too many requests! Slow down! |
500 | Internal Server Error -- We had a problem with our server. Try again later. |
503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |