Oblon

Universal REST server

Description

Oblon is a web server that gives you the capabilities to store and retrieve any (valid) JSON data, using the standard REST API (see below). You can imagine Oblon to be one big JSON file that you can manipulate partially or at once. It doesn't have a schema and it can change its structure on the fly. All the data is persisted using a single sqlite database.

Usage

Binary executable

oblon [address] [database]

Docker image

This is the recommended way to play around with Oblon. The Oblon image can be found at ghcr.io/vtashkov/oblon. It exposes port 80 as the server port and puts all the data files in the volume /data.

Example usage:

docker pull ghcr.io/vtashkov/oblon:latest

docker run -p 80:80 -v $(pwd)/data:/data -it --rm ghcr.io/vtashkov/oblon:latest

This will run Oblon in the container, exposing it on port 80 and mounting the data in the subfolder data of the current directory (which will preserve the data after shutting down the container).

API

GET

You can retrieve any part of the stored JSON by doing GET request on the particular url. If the data doesn't exist, Oblon will return 404.

Examples (using the running docker container from above):

Example 1 - All data

GET http://localhost/ - will return ALL the data stored in Oblon as one JSON document

Example 2 - Value of a field in JSON document

GET http://localhost/key1 - will return the value of the key1 field of the stored JSON (if exists).

So, if we have this JSON stored in Oblon: { "key1": "value of key1", "key2": "value of key2", "key3": "value of key3" }

the above will return simply:

"value of key1"

Note, that there are no surrounding curly braces or anything. If the value of the requested key is simple JSON (i.e. string, number or boolean), it will be returned as it is. That also means that the whole root document in Oblon can be of a simple type (or any valid JSON type).

Example 3 - Arrays

If we have the following JSON stored in Oblon: { "key1": [ "first value in key1 array", "second value in key1 array", "third value in key1 array" ], }

you can retrieve a particular value in the array like that:

http://localhost/key1/2 - will return "second value in key1 array".

Note that arrays' index start from 1.

The GET request url can be as complex as you need, you are not restricted at one level of hierarchy in the JSON document like in this examples.

PUT

You can store any valid JSON in Oblon doing PUT request on a particular url with a body containing the JSON data. If the field (or any of its parents) does not exist, it will be created. If it exists, it will be entirely replaced (but nothing in the parents will be changed) PUT requests in Oblon does not return anything in they response body (with the exception of error messages).

Examples (using the running docker container from above):

Example 1 - All data

PUT http://localhost/ - will replace all the current data in Oblon with the one you provide in the request body

Example 2 - Particular field

PUT http://localhost/key1 - will replace (or create) the data in key1 field of the root JSON document with the one you provide in the request body

Example 3 - Deep nested field

PUT http://localhost/key1/key2/key3 - will put all the provided JSON in the reponse body in the field named key3 of the document which is a value of the field key2 of the document which is a value of the field key1 of the root document. Again, it will replace any data under key3 field.

In the this example, if we have an empty database and the body of the PUT request is simple test value, then the resulting structure will be:

{ "key1": { "key2": { "key3": "test value" } } }

Note, that while you can PUT any (valid) JSON array in Oblon, you cannot expand it in any way in the current version. If you have PUT an array with 3 values and you try to PUT directly 4th element on it, this will corrupt the array. That is work in progress problem for now, along with other array-related functionalities.

DELETE

You can remove any stored JSON in Oblon doing DELETE request on a particular url. This is an equivalent of doing PUT request with null body.

Example 1 - All data

PUT http://localhost/ - will delete all stored data in Oblon

Example 2 - Particular field

PUT http://localhost/key1 - will delete the data in key1 field of the root JSON document

Future work

The immediate features that are being worked on are:

The other missing functionalities in consideration are:

In more distant future an interesting topic for exploration would be sharding(i.e. distributed system)

Licensing

Copyright (C) Victor Tashkov - All Rights Reserved This is a version for evaluation purposes only! If you are interested in commercial licensing, please contact the author.

Author

Written by Victor Tashkov vtashkov@gmail.com, 2022 .