Web interface

This section documents the Web interface (HTTP API) of BlanketDB. For simplicity we assume that BlanketDB is served at http://localhost:8080.

Create entries

To create an entry in the default bucket perform this request:

POST http://localhost:8080/

The body of the POST request may either be an arbitrary JSON object, e.g.:

{
    "a": 1.23,
    "test": "somedata"
}

or URL-encoded form content (as is created by standard HTML form submission), e.g.:

a=1.23&test=somedata

In both cases, BlanketDB will answer with a JSON object like:

{
    "id": 3,
    "bucket": "default",
    "timestamp": "2019-01-23T17:11:41.168836",
    "data": {
        "a": 1.23,
        "test": "somedata"
    }
}

If you want to store to a bucket named mybucket, post to this URL:

POST http://localhost:8080/mybucket

Retrieve entries

To retrieve an individual entry using its ID (e.g. 123), use the following request:

GET http://localhost:8080/_entry/123

BlanketDB will answer with a response similar to the post request above:

{
    "id": 123,
    "bucket": "default",
    "timestamp": "2019-01-24T06:31:36.328127",
    "data": {
        "a": 1.23,
        "test": "somedata"
    }
}

If no entry with the given ID exists, BlanketDB will respond with a 404 Not found HTTP error code. Note that you do not specify the bucket of the entry in the URL. IDs are unique across all buckets in BlanketDB.

The response above shows the data stored in entry 123 as well as corresponding metadata such as timestamp (of creation) and bucket. In order to make BlanketDB omit any metadata use

GET http://localhost:8080/_entry/123?meta=false

which will result in this reponse:

{
    "a": 1.23,
    "test": "somedata"
}

Query database

BlanketDB allows you to query entries using these filters:

  • bucket
  • since_id entries with the given ID (inclusive) or higher
  • before_id entries with an ID lower than the given one (exclusive)
  • since entries created at the given time (inclusive) or later
  • before entries created before the given time (exclusive)

The bucket is specified in the URL, the remaining filters are given as query parameters. since and before can be specified as timestamps (e.g. “2019-01-24T06:52:06.181786” or just “2019-01-24”) or as multiples of seconds, minutes or hours (e.g. “2sec”, “7s”, “3min”, “8m”, “1hour”, “2hours”, “3h”).

In order to query all entries of bucket mybucket of the last two hours, use this request:

GET http://localhost:8080/mybucket?since=2hours

BlanketDB will respond in this form:

{
    "bucket_requested": "mybucket",
    "since_id": 0,
    "since": "2019-01-24T04:59:37.925981",
    "before_id": null,
    "before": null,
    "number_of_entries": 2,
    "last_id": 4,
    "limit": null,
    "newest_first": true,
    "entries": [
        {
            "id": 4,
            "bucket": "mybucket",
            "timestamp": "2019-01-24T06:59:30.462450",
            "data": {
                "b": 1.23,
                "test": "somedata2"
            }
        },
        {
            "id": 3,
            "bucket": "mybucket",
            "timestamp": "2019-01-24T06:59:23.005946",
            "data": {
                "a": 1.23,
                "test": "somedata"
            }
        }
    ]
}

In the same way as retrieving individual entries you can omit entry metadata using

GET http://localhost:8080/mybucket?since=2hours&meta=false

which will result in:

{
    "bucket_requested": "mybucket",
    "since_id": 0,
    "since": "2019-01-24T05:00:02.552377",
    "before_id": null,
    "before": null,
    "number_of_entries": 2,
    "last_id": 4,
    "limit": null,
    "newest_first": true,
    "entries": [
        {
            "b": 1.23,
            "test": "somedata2"
        },
        {
            "a": 1.23,
            "test": "somedata"
        }
    ]
}

If you want to limit the number of entries retrieved, you can specify the limit parameter. In this context you will likely want to specify whether you are interested in the oldest or newest entries. To query the latest 3 entries in mybucket, use the following request (without metadata for brevity)

GET http://localhost:8080/mybucket?meta=false&limit=3&newest_first=true

which will result in something like this:

{
    "bucket_requested": "mybucket",
    "since_id": 0,
    "since": null,
    "before_id": null,
    "before": null,
    "number_of_entries": 3,
    "last_id": 6,
    "limit": 3,
    "newest_first": true,
    "entries": [
        {
            "b": 1.23,
            "test": "somedata2"
        },
        {
            "b": 1.23,
            "test": "somedata2"
        },
        {
            "b": 1.23,
            "test": "somedata2"
        }
    ]
}

If newest_first is not specified, it will default to true (hence the example above would work without newest_first).

In order to paginate entries you can use a combination of since_id and limit. For each subsequent request you would read the last_id field of the response, icrement by 1 and then use that number as the new since_id.

Delete entries

You can delete individual entries using the following request (for entry 123):

DELETE http://localhost:8080/_entry/123

In addition, you can apply the query filters above when deleting entries. For example, to delete all entries before today you would use the request:

DELETE http://localhost:8080/?before=today

BlanketDB will respond with the usual query metadata and a field containing the number of entries deleted:

{
    "bucket_requested": null,
    "since_id": 0,
    "since": null,
    "before_id": null,
    "before": "2019-01-24",
    "number_of_entries_deleted": 3
}