Usage

Below you will find a short walkthrough of the most important requests. We will interact with the server through it's REST API using curl. The examples assume the server to be run on the some host and listening on the port 1338.

First let us start the server:

cd /path/to/stairtower/root/
bin/server

Now we are going to test if the server is running. If we don't specify a request path, the server should respond with a welcome message:

curl http://127.0.0.1:1338/

The _stats request allows us to retrieve information about the server.

curl http://127.0.0.1:1338/_stats

To get more details simply append detailed to the request path

curl http://127.0.0.1:1338/_stats/detailed

Create a database

Create a database with name 'myDb'. The empty body will let curl set the Content-Length header which Stairtower requires for PUT and POST requests

curl -X PUT http://127.0.0.1:1338/myDb -d ""

Listing all databases should now contain 'myDb'

curl http://127.0.0.1:1338/_all_dbs

but listing the Database's Documents should return an empty set

curl http://127.0.0.1:1338/myDb

Add a Document

It's time to add a Document. If the Document body is a JSON string it is important to tell curl to send the appropriate header (--header "Content-Type:application/json").

curl --header "Content-Type:application/json" \
    -X POST http://127.0.0.1:1338/myDb \
    -d '{
    "name": "T-Shirt - Stairtower",
    "type": "clothes",
    "category": "merchandise",
    "price": 12.50,
    "options": {
        "colors": ["green", "red", "blue"],
        "size": ["xs", "s", "m", "l"]
        }
    }'

Adding two more example Documents:

curl --header "Content-Type:application/json" -X POST http://127.0.0.1:1338/myDb -d '{  "name": "Hoodie - Stairtower",  "type": "clothes",      "category": "merchandise",  "price": 19.50, "options": {    "colors": ["black", "blue"],        "size": ["s", "m", "l"] }}';
curl --header "Content-Type:application/json" -X POST http://127.0.0.1:1338/myDb -d '{  "name": "USB stick",            "type": "electronics",  "category": "merchandise",  "price": 10.50, "options": {    "memory": ["8GB", "32GB", "64GB"]   }}';

Now check if they exist in the database:

curl http://127.0.0.1:1338/myDb

Retrieving Documents

You may have recognized that the Documents have been assigned an _id property. This defines a unique identifier inside the Database. This property is indexed by default and allows fast lookups.

To retrieve a single Document you can use it's resource URI, which is built from the Database identifier and the Document identifier (e.g. myDb/f1e248d4615f716a3612d09ed2c).

curl http://127.0.0.1:1338/myDb/document_identifier

You can search by adding property value pairs as query string to the request. This example should return the hoodie and the t-shirt we added above.

curl http://127.0.0.1:1338/myDb/?type=clothes

Learn more about filtering Documents.

Managing Documents

Update

Documents are updated by sending a PUT request to the Documents resource URI. Please keep in mind that those updates do NOT patch a Document but will replace it completely.

curl --header "Content-Type:application/json" \
    -X PUT http://127.0.0.1:1338/myDb/document_identifier \
    -d '{
    "name": "T-Shirt - Stairtower",
    "type": "clothes",
    "category": "merchandise",
    "price": 13.50,
    "options": {
        "colors": ["green", "red", "blue"],
        "size": ["xs", "s", "m", "l"]
        }
    }'

Delete

To delete a Document send a DELETE request to the Documents resource URI.

curl -X DELETE http://127.0.0.1:1338/myDb/document_identifier

Learn more

Learn more about